# @dynatrace-sdk/client-document

[![npm](https://img.shields.io/badge/npm-v1.30.0-blue)](https://www.npmjs.com/package/@dynatrace-sdk/client-document/v/1.30.0)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

# Overview

This API allows you to create and manage documents, as well as manage access to them.

Have a look at the [service documentation](https://dt-url.net/platform-services-document-service) to familiarize yourself with its key concepts.

Note, that the document's content isn't inspected by the document-store, therefore it can be entirely schemaless. If your content adheres to a schema, it's your responsibility to enforce that.

Information about authorization can be found [here](https://dt-url.net/platform-services-authentication).


# Access Management

There are 2 different permission mechanisms. Most operations involve both mechanisms.

## Endpoint Permissions
IAM permissions (e.g. `document:documents:read`) guard endpoints. If the user doesn't have the permission required by an endpoint, the request gets rejected.

These permissions can not be modified via the doc-store API.

## Document Permissions
These permissions guard individual documents. They are modelled in the service itself, independent of IAM permissions.

They can be modified via the API, e.g. by using the sharing endpoints.

Therefore, a user needs to have access both in the DT IAM layer (by having specific IAM permissions) as well as access to the specific documents (e.g. by being document owner).

## Sharing

By default, documents are only accessible to their owner. There are 3 ways of sharing documents.

Documents can be made **public** (via the updateDocument operation) by the owner. This immediately grants read access to all users in the environment.

**Environment-Shares** grant read or read-write access to users of the same environment, but **users need to actively claim** the share.
The owner effectively loses control over who exactly gains access, as any user can claim the share and therefore receive access.

**Direct-Shares** immediately grant read or read-write access to **specific users and groups**. The **owner is in total control of who exactly receives access**, and can also revoke access retrospectively.

By default, every user with write-access to a document is allowed to re-share it via direct-shares and environment-shares. The owner can disable this by setting the `isReshareable` property to `false` (via the updateDocument operation).

The sharing mechanisms are not mutually exclusive - a document can be shared via multiple sharing mechanisms at the same time.

## Owner Transfer

Document ownership can be changed via the transferDocumentOwner operation.


# Document Locking

## Optimistic Locking

Operations which modify a document generally use **mandatory** optimistic locking.

When such operations are executed, the user must provide the version upon which they operate.

If the document version in the service doesn't match, because the document has been modified in the meantime, then the operation gets rejected.

## Active Locking

In addition to the mandatory Optimistic Locking, there is **optional Active Locking**.

Active locking can be optionally utilized to prevent conflicts caused by multiple users concurrently updating the same document.

A user can lock a document to prevent other users from updating the document for some time.

Once the user is done updating the document, they can release the lock and therefore enable updates by other users.


# Deletion and Restoration

Deleted documents are moved to the **trash** and permanently deleted after 30 days.

The Trash API can be used to manage deleted documents.

Restoring a deleted document makes the document accessible again for the owner as well as all users who had previously received access via shares.


# Snapshots

Document snapshots allow to reset a document's content back to an earlier state.

Snapshots must be explicitly created when updating the document. Multiple snapshots can be created per document.

Restoring a snapshot means that the document's content gets changed to the state it had when the snapshot was originally created. It doesn't change access-related data like the document's shares or ownership.

Snapshot creation is rate-limited to 5 snapshots per 60 seconds per document.

The maximum amount of snapshots per document is 50. Additional snapshots result in the deletion of the oldest existing snapshot.

All snapshots get automatically deleted after 30 days.

## Snapshot Permissions

All users with read access to a document may read its snapshots.

All users with write access to a document may create snapshots of it.

Only the owner may restore or delete a snapshot.


# Document Identity

Each document is assigned a unique and immutable identifier (id) at the time of creation.

This identifier may be supplied by the user. If the user doesn't provide one, the system will generate it automatically.

Regardless of its origin, the identifier is guaranteed to be unique across all documents and is immutable.

# Admin Access

Regular users can only access documents *owned by them* or *shared with them*.

Users with the permission `document:documents:admin` can act with elevated permission - they can access all users' documents of the current environment, regardless of ownership.

The admin-access can be enabled on a per-request basis, by setting the optional request parameter `admin-access` to `true.`

# User Data

No user data like names or email addresses are stored. Instead, SSO ids are persisted.

Every user's last access to every document gets stored to allow ordering of results so that least recently accessed documents appear first.

# System-owned Documents

Some documents are created and maintained by the system itself, instead of being user-owned.

## Ready-made Documents
Apps can contain documents which automatically become available to all users of the environment when the app gets installed or updated.
The property `originAppId` indicates app ownership.

## Extension-shipped Documents
Extensions can contain documents which automatically become available to all users of the environment when the extension gets installed or updated.
The property `originExtensionId` indicates extension ownership.



## Installation

```bash
npm install @dynatrace-sdk/client-document
```


## Getting help

- Visit [SDK for Typescript](https://developer.dynatrace.com/reference/sdks/) guide in the [Dynatrace Developer](https://developer.dynatrace.com/)
- Ask a question in the [Dynatrace Community](https://community.dynatrace.com/)


## License

This SDK is distributed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0), see LICENSE for more information.


# API reference

Full API reference for the latest version of the SDK is also available at the [Dynatrace Developer](https://developer.dynatrace.com/reference/sdks/client-document/).

## directSharesClient

```js
import { directSharesClient } from '@dynatrace-sdk/client-document';
```


<a name="adddirectsharerecipients"></a>
### addDirectShareRecipients

<div class="padding-bottom--md">
<strong>directSharesClient.addDirectShareRecipients(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Add recipients to a direct-share.

**Required scope:** document:direct-shares:write

Add one or multiple SSO-users and/or SSO-groups to this share. The affected users immediately gain access to the document.

You can only add recipients to shares which are accessible to you. Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.
The maximum number of recipients is 1000.

The validity of the SSO-users and SSO-groups isn&apos;t verified. It&apos;s technically possible, albeit pointless, to add non-existing users and groups.

Already added users or groups are ignored.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#adddirectsharerecipients">AddDirectShareRecipients</a>| |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated id of a share. |
|config.sendNotification|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether a notification shall be sent to share recipients or new document owners. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|204|The recipients have been added.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { directSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await directSharesClient.addDirectShareRecipients({
    id: "...",
    body: {
      recipients: [
        {
          id: "441664f0-23c9-40ef-b344-18c02c23d789",
          type: "group",
        },
      ],
    },
  });
```

</details>



</div>


<a name="createdirectshare"></a>
### createDirectShare

<div class="padding-bottom--md">
<strong>directSharesClient.createDirectShare(config): Promise&lt;<a href="#directshare" target="_blank" rel="noopener noreferrer">DirectShare</a>&gt;</strong>

<div class="padding-left--md">

Create a direct-share.

**Required scope:** document:direct-shares:write

Create a direct-share for a document. This is only possible for documents you own, as well as for reshareable documents owned by other users to which you have write access. The share can be used to grant access to a specific set of users and/or groups, via addRecipients.

You can optionally add users and/or groups which will directly be registered as recipients of the share. The users and groups are specified via their sso-ids. The maximum number of recipients is 1000.

The validity of the SSO-users and SSO-groups isn&apos;t verified. It&apos;s technically possible, albeit pointless, to add non-existing users and groups.

The share can be created with either `read` or `read-write` access.

A document can have maximally one direct-share per access type, therefore it&apos;s impossible to create multiple `read`-shares or multiple `read-write`-shares for a single document.

This means, that you can create one `read`-share for a document, and this single `read`-share can be used to give read-access to an arbitrary number of users (and/or groups). The same applies to a `read-write`-share.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#createdirectshare">CreateDirectShare</a>| |
|config.sendNotification|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether a notification shall be sent to share recipients or new document owners. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|[DirectShare](#directshare)|201|A new share for the specified document has been created.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|ShareAlreadyExists|Share creation failed - a share with the specified permission already exists for the document.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { directSharesClient } from "@dynatrace-sdk/client-document";

const data = await directSharesClient.createDirectShare({
  body: {
    documentId: "...",
    access: "...",
    recipients: [
      {
        id: "441664f0-23c9-40ef-b344-18c02c23d789",
        type: "group",
      },
    ],
  },
});
```

</details>



</div>


<a name="deletedirectshare"></a>
### deleteDirectShare

<div class="padding-bottom--md">
<strong>directSharesClient.deleteDirectShare(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Delete a direct-share.

**Required scope:** document:direct-shares:delete

Delete the share. This will *not* delete the share&apos;s document.

You can only delete shares which are accessible to you. Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.

This operation effectively revokes the access of all the share&apos;s recipients.

Be aware that deleting a share doesn&apos;t necessarily prevent a user from accessing a document, as the user might still have access via another share (of the same document). E.g., if a user has &apos;read&apos; and &apos;read-write&apos; access (via one &apos;read&apos; and another &apos;read-write&apos; share), and the &apos;read&apos; share gets deleted, access is still granted to the user via the other &apos;read-write&apos; share.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated id of a share. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|204|The share has been deleted.|


#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { directSharesClient } from "@dynatrace-sdk/client-document";

const data = await directSharesClient.deleteDirectShare({
  id: "...",
});
```

</details>



</div>


<a name="getdirectshare"></a>
### getDirectShare

<div class="padding-bottom--md">
<strong>directSharesClient.getDirectShare(config): Promise&lt;<a href="#directshare" target="_blank" rel="noopener noreferrer">DirectShare</a>&gt;</strong>

<div class="padding-left--md">

Retrieve a direct-share.

**Required scope:** document:direct-shares:read

Retrieve a direct-share via its id.
The share must be accessible to you. Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated id of a share. |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { directSharesClient } from "@dynatrace-sdk/client-document";

const data = await directSharesClient.getDirectShare({
  id: "...",
});
```

</details>



</div>


<a name="getdirectsharerecipients"></a>
### getDirectShareRecipients

<div class="padding-bottom--md">
<strong>directSharesClient.getDirectShareRecipients(config): Promise&lt;<a href="#directsharerecipientlist">DirectShareRecipientList</a>&gt;</strong>

<div class="padding-left--md">

List the recipients of a direct-share.

**Required scope:** document:direct-shares:read

Retrieve a share&apos;s recipients. If there are groups among the recipients, the groups always appear before the users.

You can only retrieve the recipients for shares which are accessible to you. Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated id of a share. |
|config.page|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.</p>  |
|config.pageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The page key is used to query results from the next page. You get a <code>nextPageKey</code> parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.</p>  |
|config.pageSize|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.</p>  |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { directSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await directSharesClient.getDirectShareRecipients({
    id: "...",
  });
```

</details>



</div>


<a name="listdirectshares"></a>
### listDirectShares

<div class="padding-bottom--md">
<strong>directSharesClient.listDirectShares(config): Promise&lt;<a href="#directsharelist" target="_blank" rel="noopener noreferrer">DirectShareList</a>&gt;</strong>

<div class="padding-left--md">

List all direct-shares accessible to you.

**Required scope:** document:direct-shares:read

List all direct-shares accessible to you.
Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access. If you are only concerned with a specific document&apos;s shares, or a specific share, you can use the `filter` parameter to narrow down the result set. If you attempt to retrieve shares which are not accessible to you the result set will be empty.

*Note, that at the moment we offer a naive pagination, and therefore interim mutations can lead to result inconsistencies (such as duplicates, missing entries).*



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.filter|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The filter query, as explained <a href="https://dt-url.net/platform-services-filtering" target="_blank" rel="noopener noreferrer" >here</a>. Filtering is only possible on the <code>documentId</code> property, and only with the equals operator. Via this you can effectively retrieve the direct-shares of a specific document. If this parameter is omitted, all direct-shares accessible to you will be returned. |
|config.page|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.</p>  |
|config.pageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The page key is used to query results from the next page. You get a <code>nextPageKey</code> parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.</p>  |
|config.pageSize|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.</p>  |
|config.sendNotification|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether a notification shall be sent to share recipients or new document owners. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|[DirectShareList](#directsharelist)|200|A list of direct-shares accessible to you.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { directSharesClient } from "@dynatrace-sdk/client-document";

const data = await directSharesClient.listDirectShares();
```

</details>



</div>


<a name="removedirectsharerecipients"></a>
### removeDirectShareRecipients

<div class="padding-bottom--md">
<strong>directSharesClient.removeDirectShareRecipients(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Remove recipients from a share.

**Required scope:** document:direct-shares:write

Remove one or multiple recipients from the share. The affected users immediately lose access to the document.

You can only remove recipients from shares which are accessible to you. Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.
The maximum number of recipients is 1000.

Non-existing users or groups are ignored.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#removedirectsharerecipients">RemoveDirectShareRecipients</a>| |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated id of a share. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|204|The recipients have been removed.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { directSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await directSharesClient.removeDirectShareRecipients({
    id: "...",
    body: { ids: ["..."] },
  });
```

</details>



</div>

## documentLockingClient

```js
import { documentLockingClient } from '@dynatrace-sdk/client-document';
```


<a name="acquirelock"></a>
### acquireLock

<div class="padding-bottom--md">
<strong>documentLockingClient.acquireLock(config): Promise&lt;<a href="#acquirelockresult" target="_blank" rel="noopener noreferrer">AcquireLockResult</a>&gt;</strong>

<div class="padding-left--md">

Acquire the lock on the document.

**Required scope:** document:documents:write

Acquire the lock on the document. A user can lock a maximum of five documents at any given time. Once the lock is acquired by the user, other users cannot make any updates to the document.

The user acquiring the lock can optionally specify the duration for which the lock can be attained. However, the specified duration must not exceed the maximum allowed duration of 15 minutes. If not specified, the lock is acquired for 10 minutes.

If the user who has currently locked the document attempts to acquire the lock for the same document again, the duration of the lock gets extended by the specified duration or by a default duration of 10 minutes, if not specified.

The other users would not be allowed to acquire the lock on an already locked document.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.body<sup>*required</sup>|<a href="#acquirelock">AcquireLock</a>| |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|[AcquireLockResult](#acquirelockresult)|200|The lock has been acquired by the user.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|DocumentAlreadyLocked|Lock acquisition failed as the document is already locked.|
|LockedDocumentsLimitReached|Lock acquisition failed as number of locked documents reached or exceeded the allowed limit.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentLockingClient } from "@dynatrace-sdk/client-document";

const data = await documentLockingClient.acquireLock({
  id: "...",
  body: { documentVersion: 10 },
});
```

</details>



</div>


<a name="inspectlock"></a>
### inspectLock

<div class="padding-bottom--md">
<strong>documentLockingClient.inspectLock(config): Promise&lt;<a href="#documentlockdetails" target="_blank" rel="noopener noreferrer">DocumentLockDetails</a>&gt;</strong>

<div class="padding-left--md">

Inspect whether the document is locked.

**Required scope:** document:documents:read

Inspect whether the document is locked.

This provides the information about whether the document is locked and the user that currently owns the lock.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |





#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentLockingClient } from "@dynatrace-sdk/client-document";

const data = await documentLockingClient.inspectLock({
  id: "...",
});
```

</details>



</div>


<a name="releaselock"></a>
### releaseLock

<div class="padding-bottom--md">
<strong>documentLockingClient.releaseLock(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Release the lock on the document.

**Required scope:** document:documents:write

Release the lock on the document.
The lock on the document can be released only by the user who owns it.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|200|The lock on the document has been released.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentLockingClient } from "@dynatrace-sdk/client-document";

const data = await documentLockingClient.releaseLock({
  id: "...",
});
```

</details>



</div>

## documentsClient

```js
import { documentsClient } from '@dynatrace-sdk/client-document';
```


<a name="bulkdeletedocument"></a>
### bulkDeleteDocument

<div class="padding-bottom--md">
<strong>documentsClient.bulkDeleteDocument(config): Promise&lt;<a href="#bulkdeleteresponse">BulkDeleteResponse</a>&gt;</strong>

<div class="padding-left--md">

Bulk-delete multiple documents

**Required scope:** document:documents:delete

Move the documents with the given ids into the trash. They are no longer accessible until they&apos;re restored from the trash. &lt;p&gt;The number of provided document ids is limited to 100.&lt;/p&gt;



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#bulkdeleterequest" target="_blank" rel="noopener noreferrer">BulkDeleteRequest</a>| |





#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.bulkDeleteDocument({
  body: { ids: ["..."] },
});
```

</details>



</div>


<a name="createdocument"></a>
### createDocument

<div class="padding-bottom--md">
<strong>documentsClient.createDocument(config): Promise&lt;<a href="#documentmetadata">DocumentMetaData</a>&gt;</strong>

<div class="padding-left--md">

Create a new document.

**Required scope:** document:documents:write

Create a new document. You are the owner of the created document. The document isn&apos;t accessible to other users.

The document&apos;s `name` and `type` must be provided. These two properties can later be used for filtering purposes, when listing accessible documents.

Be aware, that the `type` isn&apos;t the same as the Content-Type of the document, but instead adds user-defined semantics of which the document-store is entirely agnostic.

The content size must not exceed **50 MB**.



</div>


#### Parameters

| Name | Type |
| --- | --- |
|config.body<sup>*required</sup>|<a href="#createdocumentbody" target="_blank" rel="noopener noreferrer">CreateDocumentBody</a>| 





#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ExternalIdAlreadyExists|Deprecated, replaced by IdAlreadyExists. A document with the given external id already exists in this environment.|
|DocumentTooLarge|Maximum content size exceeded.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|
|InsufficientStorage|The storage quota or maximum number of documents has been exceeded.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.createDocument({
  body: { name: "...", type: "...", content: "..." },
});
```

</details>



</div>


<a name="deletedocument"></a>
### deleteDocument

<div class="padding-bottom--md">
<strong>documentsClient.deleteDocument(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Delete the document

**Required scope:** document:documents:delete

Move the document into the trash. It is no longer accessible until it&apos;s restored from the trash.

[Optimistic locking](https://dt-url.net/platform-services-locking) is enforced via the `optimistic-locking-version` parameter.

You must own the document to delete it.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.optimisticLockingVersion<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|To protect users from accidental overrides, the current version of the document must match the optimistic locking version parameter - otherwise, this request will fail and the entity is left unchanged. |





#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|Conflict|Optimistic locking failed, or the document is actively locked by another user, or some other conflict.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.deleteDocument({
  id: "...",
  optimisticLockingVersion: "...",
});
```

</details>



</div>


<a name="deletesnapshot"></a>
### deleteSnapshot

<div class="padding-bottom--md">
<strong>documentsClient.deleteSnapshot(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Delete the snapshot.

**Required scope:** document:documents:write

Irrevocably delete the snapshot. Only the document owner may do this.

This operation doesn&apos;t affect the current state of the document.

Instead, it prevents that the document may ever be restored to the state it had when the snapshot was created.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.snapshotVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|System-generated snapshot version. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|204|The snapshot has been deleted.|


#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|SnapshotNotFound|Snapshot not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.deleteSnapshot({
  id: "...",
  snapshotVersion: 10,
});
```

</details>



</div>


<a name="downloaddocumentcontent"></a>
### downloadDocumentContent

<div class="padding-bottom--md">
<strong>documentsClient.downloadDocumentContent(config): Promise&lt;Binary&gt;</strong>

<div class="padding-left--md">

Download document content

**Required scope:** document:documents:read

Download latest document content.

If the `snapshot-version` param is provided, the content of the specified snapshot gets returned instead. This requires write-access to the document.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

The response&apos;s `Content-Type` header has the same value that has been used during the upload.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.filename|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The optional <code>filename</code> query parameter can be passed to give the file that's being downloaded a user-provided name and file extension for downloading purposes. This name will be sent back to the client via the Content-Disposition HTTP header. The passed <code>filename</code> will be trimmed so that it doesn't contain any space characters around the name. When the <code>filename</code> isn't specified, then the name of the document is used as file name and no extension is added, since the service isn't aware of file extensions. |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.snapshotVersion|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Snapshot version, to be used if you want to access a snapshot of the document. |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentOrSnapshotNotFound|Document or snapshot not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.downloadDocumentContent({
  id: "...",
});
```

</details>



</div>


<a name="getdocument"></a>
### getDocument

<div class="padding-bottom--md">
<strong>documentsClient.getDocument(config): Promise&lt;<a href="#getdocumentresponse">GetDocumentResponse</a>&gt;</strong>

<div class="padding-left--md">

Retrieve metadata and content.

**Required scope:** document:documents:read

Return metadata and content in one multipart response.

If the `snapshot-version` param is provided, the metadata and content of the specified snapshot gets returned instead. This requires write-access to the document.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.addFields|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>Comma-separated list of field names that are added to the default set of fields. You can include the following additional fields:</p> <ul> <li><code>userContext.lastAccessedTime</code></li> <li><code>modificationInfo.lastModifyingAppId</code></li> </ul>  |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.filename|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The optional <code>filename</code> query parameter can be passed to give the file that's being downloaded a user-provided name and file extension for downloading purposes. This name will be sent back to the client via the Content-Disposition HTTP header. The passed <code>filename</code> will be trimmed so that it doesn't contain any space characters around the name. When the <code>filename</code> isn't specified, then the name of the document is used as file name and no extension is added, since the service isn't aware of file extensions. |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.snapshotVersion|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Snapshot version, to be used if you want to access a snapshot of the document. |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentOrSnapshotNotFound|Document or snapshot not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.getDocument({
  id: "...",
});
```

</details>



</div>


<a name="getdocumentmetadata"></a>
### getDocumentMetadata

<div class="padding-bottom--md">
<strong>documentsClient.getDocumentMetadata(config): Promise&lt;<a href="#documentmetadata" target="_blank" rel="noopener noreferrer">DocumentMetaData</a>&gt;</strong>

<div class="padding-left--md">

Retrieve document metadata.

**Required scope:** document:documents:read

Retrieve a document&apos;s metadata.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

If the `snapshot-version` param is provided, the metadata of the specified snapshot gets returned instead. This requires write-access to the document.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.addFields|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>Comma-separated list of field names that are added to the default set of fields. You can include the following additional fields:</p> <ul> <li><code>userContext.lastAccessedTime</code></li> <li><code>modificationInfo.lastModifyingAppId</code></li> </ul>  |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.snapshotVersion|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Snapshot version, to be used if you want to access a snapshot of the document. |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentOrSnapshotNotFound|Document or snapshot not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.getDocumentMetadata({
  id: "...",
});
```

</details>



</div>


<a name="getsnapshotmetadata"></a>
### getSnapshotMetadata

<div class="padding-bottom--md">
<strong>documentsClient.getSnapshotMetadata(config): Promise&lt;<a href="#snapshotmetadata">SnapshotMetadata</a>&gt;</strong>

<div class="padding-left--md">

Retrieve snapshot metadata.

**Required scope:** document:documents:read

Retrieve snapshot metadata. Requires write-access to the document.

This doesn&apos;t return data of the snapshotted document, instead it returns data about the snapshot itself.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.snapshotVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|System-generated snapshot version. |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|SnapshotNotFound|Snapshot not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.getSnapshotMetadata({
  id: "...",
  snapshotVersion: 10,
});
```

</details>



</div>


<a name="listdocuments"></a>
### listDocuments

<div class="padding-bottom--md">
<strong>documentsClient.listDocuments(config): Promise&lt;<a href="#documentlist" target="_blank" rel="noopener noreferrer">DocumentList</a>&gt;</strong>

<div class="padding-left--md">

List all documents accessible to you.

**Required scope:** document:documents:read

List the metadata of all documents accessible to you.


This includes your own documents, as well as other users&apos; documents which have been shared with you.


*Note, that at the moment we offer a naive pagination, and therefore interim document mutations and/or an
insufficient sort clause, if provided, can lead to result inconsistencies (such as duplicates, missing entries).*



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.addFields|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>Comma-separated list of field names that are added to the default set of fields. You can include the following additional fields:</p> <ul> <li><code>description</code></li> <li><code>userContext.lastAccessedTime</code></li> <li><code>originExtensionId</code></li> <li><code>shareInfo.isShared</code></li> <li><code>shareInfo.isSharedWithCurrentUser</code></li> </ul>  |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.filter|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The filter parameter, as explained <a href="https://dt-url.net/platform-services-filtering" target="_blank" rel="noopener noreferrer" >here</a>.</p> <p>If this parameter is omitted, no filtering is applied and all documents available to you will be returned.</p> <p>Filtering by string type parameters (<code>name</code>, <code>type</code>) when using one of the operators <code>contains</code>, <code>starts-with</code> and <code>ends-with</code> is <strong>case insensitive</strong>.</p> <p>Filtering by <code>id</code> using the operators <code>contains</code>, <code>starts-with</code> and <code>ends-with</code> is only supported in case of user-given document ids.</p> <p>When using the equals operator or the not-equals operator, filtering is <strong>case sensitive</strong>.</p> <p>The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response:</p> <p><code>id</code>, <code>name</code>, <code>type</code>, <code>version</code>, <code>owner</code>, <code>modificationInfo.createdTime</code>, <code>modificationInfo.createdBy</code>, <code>modificationInfo.lastModifiedTime</code>, <code>modificationInfo.lastModifiedBy</code>, <code>originAppId</code>, <code>originExtensionId</code></p> <p>The following constraints apply:</p> <ul> <li> <p>Parameter names are <strong>case-sensitive</strong>.</p> </li> <li> <p>Maximum nesting depth (via brackets) is 3.</p> </li> <li> <p>Maximum length is 1024 characters.</p> </li> </ul> <p>Examples:</p> <ul> <li> <p><code>name = 'my-document-name'</code></p> </li> <li> <p><code>name == 'my-document-name'</code></p> </li> <li> <p><code>(name starts-with 'awesome' or type != 'dashboard') and version &gt;= 5</code></p> </li> <li> <p><code>modificationInfo.lastModifiedTime &gt;= '2022-07-01T00:10:05.000Z' and not (name contains 'new')</code></p> </li> <li> <p><code>originAppId exists</code></p> </li> <li> <p><code>originExtensionId exists</code></p> </li> <li> <p><code>type in ('dashboard', 'notebook') and name contains 'report'</code></p> </li> </ul>  |
|config.page|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.</p>  |
|config.pageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The page key is used to query results from the next page. You get a <code>nextPageKey</code> parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.</p>  |
|config.pageSize|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.</p>  |
|config.sort|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The sort parameter, as explained <a href="https://dt-url.net/platform-services-filtering" target="_blank" rel="noopener noreferrer" >here</a></p> <p>If this parameter is omitted, the documents are sorted by their ids.</p> <p>Sorting by string types (<code>name</code>, <code>type</code>) is done in a case insensitive manner.</p> <p>The following fields are legal sorting parameters - any other sorting parameters will result in a HTTP 400 response:</p> <ul> <li><code>name</code>,  <code>type</code>,  <code>version</code>, <code>owner</code>, <code>modificationInfo.createdTime</code>, <code>modificationInfo.createdBy</code>, <code>modificationInfo.lastModifiedTime</code>,<code>modificationInfo.lastModifiedBy</code>,<code>originAppId</code>, <code>userContext.lastAccessedTime</code></li> </ul> <p>The following constraints apply:</p> <ul> <li> <p>Maximum number of sorting parameters is 5. Exceeding this limit will result in a HTTP 400 response.</p> </li> <li> <p>Note that blanks are <em>not</em> ignored and will result in a HTTP 400 response.</p> </li> </ul> <p>Examples:</p> <ul> <li> <p><code>name</code></p> </li> <li> <p><code>name,-type,modificationInfo.lastModifiedTime</code></p> </li> </ul>  |





#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.listDocuments();
```

</details>



</div>


<a name="listsnapshots"></a>
### listSnapshots

<div class="padding-bottom--md">
<strong>documentsClient.listSnapshots(config): Promise&lt;<a href="#snapshotlist">SnapshotList</a>&gt;</strong>

<div class="padding-left--md">

List all snapshots of the document

**Required scope:** document:documents:read

Returns metadata of all snapshots of the document, in descending order of the snapshot&apos;s creation date. Requires write-access to the document.

You can apply pagination via the `pageKey` and `pageSize` parameters.

*Note, that at the moment we offer a naive pagination, and therefore interim mutations can lead to result inconsistencies (such as duplicates, missing entries).*



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.page|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.</p>  |
|config.pageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The page key is used to query results from the next page. You get a <code>nextPageKey</code> parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.</p>  |
|config.pageSize|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.</p>  |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.listSnapshots({
  id: "...",
});
```

</details>



</div>


<a name="restoresnapshot"></a>
### restoreSnapshot

<div class="padding-bottom--md">
<strong>documentsClient.restoreSnapshot(config): Promise&lt;<a href="#restoredocumentresult" target="_blank" rel="noopener noreferrer">RestoreDocumentResult</a>&gt;</strong>

<div class="padding-left--md">

Restore the snapshot.

**Required scope:** document:documents:write

Reset the document to the state it had when the snapshot was created. Requires write-access to the document.

If no snapshot of the current document state exists, then a new snapshot is created
before restoring the selected snapshot.
If the document has more than 50 snapshots, its oldest snapshot gets automatically deleted.

This operation only changes the document&apos;s content. It doesn&apos;t change ownership or access/sharing data.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.snapshotVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|System-generated snapshot version. |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentOrSnapshotNotFound|Document or snapshot not found.|
|Conflict|Optimistic locking failed, or the document is actively locked by another user, or some other conflict.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.restoreSnapshot({
  id: "...",
  snapshotVersion: 10,
});
```

</details>



</div>


<a name="transferdocumentowner"></a>
### transferDocumentOwner

<div class="padding-bottom--md">
<strong>documentsClient.transferDocumentOwner(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Transfers ownership of the document to a new owner.

**Required scope:** document:documents:write

Transfers ownership of the document to a new owner. The previous owner loses access to the document. This operation can only be performed by the document owner.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#transferowner">TransferOwner</a>| |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.sendNotification|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether a notification shall be sent to share recipients or new document owners. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|204|Ownership has been transferred successfully.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|Conflict|Optimistic locking failed, or the document is actively locked by another user, or some other conflict.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.transferDocumentOwner({
  id: "...",
  body: { newOwnerId: "..." },
});
```

</details>



</div>


<a name="updatedocument"></a>
### updateDocument

<div class="padding-bottom--md">
<strong>documentsClient.updateDocument(config): Promise&lt;<a href="#updatedocumentmetadata" target="_blank" rel="noopener noreferrer">UpdateDocumentMetadata</a>&gt;</strong>

<div class="padding-left--md">

Update metadata and content. Optionally, create a snapshot.

**Required scope:** document:documents:write

Update metadata and/or the content of the document.

Name, type, and content must be non-empty. Name, type, content, isPrivate and isReshareable are optional, but at least one of them must be provided.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

As part of this operation, you can optionally create a snapshot of the updated document.
In that case, if the document has more than 50 snapshots, its oldest snapshot gets automatically deleted.
It&apos;s impossible to create more than 5 snapshots per 60 seconds, per document.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#updatedocumentbody">UpdateDocumentBody</a>| |
|config.createSnapshot|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether a new snapshot shall be created after the update was executed. |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.optimisticLockingVersion<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|To protect users from accidental overrides, the current version of the document must match the optimistic locking version parameter - otherwise, this request will fail and the entity is left unchanged. |





#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|Conflict|Optimistic locking failed, or the document is actively locked by another user, or some other conflict.|
|DocumentTooLarge|Maximum content size exceeded.|
|SnapshotCreationRateLimitExceeded|Too many snapshots have been created for this document in the recent time. Try again later.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|
|InsufficientStorage|The storage quota or maximum number of documents has been exceeded.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.updateDocument({
  id: "...",
  optimisticLockingVersion: "...",
  body: {},
});
```

</details>



</div>


<a name="updatedocumentcontent"></a>
### updateDocumentContent

<div class="padding-bottom--md">
<strong>documentsClient.updateDocumentContent(config): Promise&lt;<a href="#documentmetadata" target="_blank" rel="noopener noreferrer">DocumentMetaData</a>&gt;</strong>

<div class="padding-left--md">

Update document content

**Required scope:** document:documents:write

Update a document&apos;s content, by completely replacing it.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

[Optimistic locking](https://dt-url.net/platform-services-locking) is enforced via the `optimistic-locking-version` parameter.

The content size must be greater than 0 and must not exceed `50 MB`.

The `Content-Type` header must be set for the multipart part; it will be used as the (new) content type of the document. Illegal (non-mime-type) content types result in a `400 - Bad Request` error.

The `Content-Disposition` header must be set for the multipart part;



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#updatedocumentcontentbody">UpdateDocumentContentBody</a>| |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.optimisticLockingVersion<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|To protect users from accidental overrides, the current version of the document must match the optimistic locking version parameter - otherwise, this request will fail and the entity is left unchanged. |





#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|Conflict|Optimistic locking failed, or the document is actively locked by another user, or some other conflict.|
|DocumentTooLarge|Maximum content size exceeded.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|
|InsufficientStorage|The storage quota or maximum number of documents has been exceeded.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.updateDocumentContent({
  id: "...",
  optimisticLockingVersion: "...",
  body: { content: "..." },
});
```

</details>



</div>


<a name="updatedocumentmetadata"></a>
### ~~updateDocumentMetadata~~

> ⚠️ **Deprecated**

<div class="padding-bottom--md">
<strong>documentsClient.updateDocumentMetadata(config): Promise&lt;<a href="#documentmetadata" target="_blank" rel="noopener noreferrer">DocumentMetaData</a>&gt;</strong>

<div class="padding-left--md">

Update document metadata

**Required scope:** document:documents:write

Deprecated - the preferred way to update a document is the updateDocument operation.

Partially update a document&apos;s user-defined metadata. At least one property must be updated, otherwise the operation fails.

The document&apos;s content isn&apos;t affected by this operation.

[Optimistic locking](https://dt-url.net/platform-services-locking) is enforced via the `optimistic-locking-version` parameter.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#updatedocumentmetadatabody">UpdateDocumentMetadataBody</a>| |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|config.optimisticLockingVersion<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|To protect users from accidental overrides, the current version of the document must match the optimistic locking version parameter - otherwise, this request will fail and the entity is left unchanged. |





#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|Conflict|Optimistic locking failed, or the document is actively locked by another user, or some other conflict.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { documentsClient } from "@dynatrace-sdk/client-document";

const data = await documentsClient.updateDocumentMetadata({
  id: "...",
  optimisticLockingVersion: "...",
  body: {},
});
```

</details>



</div>

## environmentSharesClient

```js
import { environmentSharesClient } from '@dynatrace-sdk/client-document';
```


<a name="claimenvironmentshare"></a>
### claimEnvironmentShare

<div class="padding-bottom--md">
<strong>environmentSharesClient.claimEnvironmentShare(config): Promise&lt;<a href="#environmentshareclaimresult" target="_blank" rel="noopener noreferrer">EnvironmentShareClaimResult</a>&gt;</strong>

<div class="padding-left--md">

Claim another user&apos;s environment-share.

**Required scope:** document:environment-shares:claim

Claim this environment-share, therefore gaining access to the share&apos;s document. From thereafter, the document will be accessible to you with the specific permissions defined by the share. You can then access the document as usual, via the same endpoints which you would use to access your own documents.

Claiming your own shares isn&apos;t possible. You can only claim shares of documents belonging to other users *of the same environment*.

Once you have claimed access to a document, you can not revoke that access again.

The document&apos;s owner can revoke your access by deleting the share. This will effectively revoke the access you have been granted by claiming this share.

You can claim multiple shares of the same document, and each share will grant you different permissions.

Claiming the same share multiple times doesn&apos;t have any effect.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Share id. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|[EnvironmentShareClaimResult](#environmentshareclaimresult)|200|You have successfully claimed this share and can now access the document with the granted permissions.|


#### Throws

| Error Type | Error Message |
|---|---|
|ClaimingOwnedShareNotAllowed|A user can't claim one of their own shares.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { environmentSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await environmentSharesClient.claimEnvironmentShare({
    id: "...",
  });
```

</details>



</div>


<a name="createenvironmentshare"></a>
### createEnvironmentShare

<div class="padding-bottom--md">
<strong>environmentSharesClient.createEnvironmentShare(config): Promise&lt;<a href="#environmentshare">EnvironmentShare</a>&gt;</strong>

<div class="padding-left--md">

Create an environment-share for a document.

**Required scope:** document:environment-shares:write

Create an environment-share, which can be used to give one or multiple other users access to this document. This is only possible for documents you own, as well as for reshareable documents owned by other users to which you have write access.
A share can be created with either `read` or `read-write` access.

A document can have maximally one share per access type, therefore it&apos;s impossible to create multiple read-shares or multiple &apos;read-write&apos;-shares for a single document.

This means, that you can create one read-share for a document, and this single read-share can be used to give read-access to an arbitrary number of users. The same applies to a &apos;read-write&apos;-share.

Creating a share does *not* automatically allow users to access the document - only those users who explicitly claim the share gain access to the document.

Revoking access from users can be done by deleting the share.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.body<sup>*required</sup>|<a href="#createenvshare" target="_blank" rel="noopener noreferrer">CreateEnvShare</a>| |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|[EnvironmentShare](#environmentshare)|201|A new environment-share for the specified document has been created.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|DocumentNotFound|Document not found.|
|ShareAlreadyExists|Share creation failed - a share with the specified permission already exists for the document.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { environmentSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await environmentSharesClient.createEnvironmentShare({
    body: { documentId: "...", access: "..." },
  });
```

</details>



</div>


<a name="deleteenvironmentshare"></a>
### deleteEnvironmentShare

<div class="padding-bottom--md">
<strong>environmentSharesClient.deleteEnvironmentShare(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Delete an environment-share accessible to you.

**Required scope:** document:environment-shares:delete

Delete the share. This will *not* delete the share&apos;s document.

The share must be accessible to you. Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.

This operation effectively revokes the access which has been granted to *all users* which have claimed this share. This is the only way to revoke access to your document from other users. It&apos;s impossible to revoke access of individual users.

Be aware that deleting a share doesn&apos;t necessarily prevent a user from accessing a document, as the user might still have access via another share (of the same document). E.g., if a user has read- and readwrite-access (via one read-share and another readwrite-share), and the read-share gets deleted, access is still granted to the user via the readwrite-share.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Environment-share id. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|204|The share has been deleted.|


#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { environmentSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await environmentSharesClient.deleteEnvironmentShare({
    id: "...",
  });
```

</details>



</div>


<a name="getenvironmentshare"></a>
### getEnvironmentShare

<div class="padding-bottom--md">
<strong>environmentSharesClient.getEnvironmentShare(config): Promise&lt;<a href="#environmentshare">EnvironmentShare</a>&gt;</strong>

<div class="padding-left--md">

Retrieve an environment-share.

**Required scope:** document:environment-shares:read

Retrieve an environment-share via its id.
The share must be accessible to you. Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Environment-share id. |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { environmentSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await environmentSharesClient.getEnvironmentShare({
    id: "...",
  });
```

</details>



</div>


<a name="getenvironmentshareclaimers"></a>
### getEnvironmentShareClaimers

<div class="padding-bottom--md">
<strong>environmentSharesClient.getEnvironmentShareClaimers(config): Promise&lt;<a href="#environmentshareclaimerlist" target="_blank" rel="noopener noreferrer">EnvironmentShareClaimerList</a>&gt;</strong>

<div class="padding-left--md">

List the claimers of an environment-share accessible to you.

**Required scope:** document:environment-shares:read


Retrieve a share&apos;s claimers.

The share must be accessible to you.
Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.

You can control the result&apos;s pagination via the `pageKey`, `page` and `pageSize` parameters.

*Note, that at the moment we offer a naive pagination, and therefore interim document mutations and/or an
insufficient sort clause, if provided, can lead to result inconsistencies (such as duplicates, missing entries).*



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Environment-share id. |
|config.page|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.</p>  |
|config.pageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The page key is used to query results from the next page. You get a <code>nextPageKey</code> parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.</p>  |
|config.pageSize|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.</p>  |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|ShareNotFound|Share not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { environmentSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await environmentSharesClient.getEnvironmentShareClaimers(
    { id: "..." },
  );
```

</details>



</div>


<a name="listenvironmentshares"></a>
### listEnvironmentShares

<div class="padding-bottom--md">
<strong>environmentSharesClient.listEnvironmentShares(config): Promise&lt;<a href="#environmentsharelist">EnvironmentShareList</a>&gt;</strong>

<div class="padding-left--md">

List environment-shares accessible to you.

**Required scope:** document:environment-shares:read

List all environment-shares accessible to you.
Shares accessible to you include those of your own documents, as well as those of reshareable documents owned by other users to which you have write access.
If you are only concerned with a specific document&apos;s environment-shares, or a specific share, you can use the `filter` parameter to narrow down the result set. If you attempt to retrieve environment-shares of a document not accessible by you, the result set will be empty.

Furthermore, you can apply pagination via the `pageKey`, `page` and `pageSize` parameters.

*Note, that at the moment we offer a naive pagination, and therefore interim mutations can lead to result inconsistencies (such as duplicates, missing entries).*



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.filter|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The filter query, as explained <a href="https://dt-url.net/platform-services-filtering" target="_blank" rel="noopener noreferrer" >here</a>. Filtering is only possible on the <code>documentId</code> property, and only via the equals operator. Via this you can effectively retrieve the environment-shares of a specific document. If this parameter is omitted, all environment-shares accessible to you will be returned. |
|config.page|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.</p>  |
|config.pageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The page key is used to query results from the next page. You get a <code>nextPageKey</code> parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.</p>  |
|config.pageSize|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.</p>  |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|[EnvironmentShareList](#environmentsharelist)|200|A list of the environment-shares accessible to you.
If the list was paginated (see `pageKey`, `page` and `pageSize`), and there are more environment-shares available, you will find a non-empty `nextPageKey` which can be used for a follow-up query. The `totalCount` property will let you know the number of all matching environment-shares, as if no pagination would have been applied.|


#### Throws

| Error Type | Error Message |
|---|---|
|BadRequest|Malformed request or invalid parameters.|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { environmentSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await environmentSharesClient.listEnvironmentShares();
```

</details>



</div>

## trashClient

```js
import { trashClient } from '@dynatrace-sdk/client-document';
```


<a name="deletetrasheddocument"></a>
### deleteTrashedDocument

<div class="padding-bottom--md">
<strong>trashClient.deleteTrashedDocument(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Irreversibly destroy the document.

**Required scope:** document:trash.documents:delete

This operation irreversibly destroys the document.
Only the document owner is permitted to do this.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|204|The document has been permanently deleted.|


#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|TrashedDocumentNotFound|Trashed document not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { trashClient } from "@dynatrace-sdk/client-document";

const data = await trashClient.deleteTrashedDocument({
  id: "...",
});
```

</details>



</div>


<a name="inspecttrasheddocument"></a>
### inspectTrashedDocument

<div class="padding-bottom--md">
<strong>trashClient.inspectTrashedDocument(config): Promise&lt;<a href="#trashdocument" target="_blank" rel="noopener noreferrer">TrashDocument</a>&gt;</strong>

<div class="padding-left--md">

Inspect the deleted document.

**Required scope:** document:trash.documents:read

Inspect the deleted document&apos;s metadata.
Only the document owner is permitted to do this.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|TrashedDocumentNotFound|Trashed document not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { trashClient } from "@dynatrace-sdk/client-document";

const data = await trashClient.inspectTrashedDocument({
  id: "...",
});
```

</details>



</div>


<a name="listtrasheddocuments"></a>
### listTrashedDocuments

<div class="padding-bottom--md">
<strong>trashClient.listTrashedDocuments(config): Promise&lt;<a href="#trashdocumentlist">TrashDocumentList</a>&gt;</strong>

<div class="padding-left--md">

List your deleted documents.

**Required scope:** document:trash.documents:read

Lists all documents, owned by you, which currently reside in the trash.

Note that documents in the trash are irreversibly deleted after 30 days.

*Note that at the moment we offer a naive pagination, and therefore interim document mutations and/or an
    insufficient sort clause, if provided, can lead to result inconsistencies (such as duplicates, missing entries).*



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.filter|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The filter parameter, as explained <a href="https://dt-url.net/platform-services-filtering" target="_blank" rel="noopener noreferrer" >here</a>.</p> <p>If this parameter is omitted, no filtering is applied and all your deleted documents will be returned.</p> <p>Filtering by string type parameters when using one of the operators <code>contains</code>, <code>starts-with</code> and <code>ends-with</code> is <strong>case insensitive</strong>.</p> <p>Filtering by <code>id</code> using the operators <code>contains</code>, <code>starts-with</code> and <code>ends-with</code> is only supported in case of user-given document ids.</p> <p>When using the equals operator or the not-equals operator, filtering is <strong>case sensitive</strong>.</p> <p>The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response:</p> <p><code>id</code>, <code>name</code>, <code>type</code>, <code>deletionInfo.deletedTime</code>, <code>deletionInfo.deletedBy</code></p> <p>The following constraints apply:</p> <ul> <li> <p>Parameter names are <strong>case-sensitive</strong>.</p> </li> <li> <p>Maximum nesting depth (via brackets) is 3.</p> </li> <li> <p>Maximum length is 1024 characters.</p> </li> </ul>  |
|config.page|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.</p>  |
|config.pageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The page key is used to query results from the next page. You get a <code>nextPageKey</code> parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.</p>  |
|config.pageSize|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.</p>  |





#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { trashClient } from "@dynatrace-sdk/client-document";

const data = await trashClient.listTrashedDocuments();
```

</details>



</div>


<a name="restoretrasheddocument"></a>
### restoreTrashedDocument

<div class="padding-bottom--md">
<strong>trashClient.restoreTrashedDocument(config): Promise&lt;void&gt;</strong>

<div class="padding-left--md">

Restore the deleted document.

**Required scope:** document:trash.documents:restore

This operation restores the document from the trash.
All users who had access before the deletion regain their access to the document.
Only the document owner is permitted to do this.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|config.adminAccess|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the operation should be performed with elevated permissions - additionally requires <strong>document:documents:admin</strong>.</p> <p>If provided, the user effectively operates as owner of all documents. This isn't supported for ready-made documents.</p>  |
|config.id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |




#### Returns

| Return type | Status code | Description |
|---|---|---|
|void|204|The document has been restored.|


#### Throws

| Error Type | Error Message |
|---|---|
|Unauthorized|API token or tenant missing or corrupt.|
|Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.|
|TrashedDocumentNotFound|Trashed document not found.|
|InternalServerError|There is a problem in the backend.|
|ServiceUnavailable|There is a temporary problem in the backend.|


<details>
<summary>
Code example
</summary>

```ts
import { trashClient } from "@dynatrace-sdk/client-document";

const data = await trashClient.restoreTrashedDocument({
  id: "...",
});
```

</details>



</div>

## Types

### AcquireLock

Input to acquire the lock.

| Name | Type | Description |
| --- | --- | --- |
|documentVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The latest version of the document. |
|lockDurationInSeconds|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Duration specified in seconds to acquire the lock on the document. |

### AcquireLockResult

| Name | Type | Description |
| --- | --- | --- |
|documentVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The latest version of the document. |
|lockedUntil<sup>*required</sup>|Date|Timestamp until the document remains locked. |

### AddDirectShareRecipients

Input required to add recipients to a direct-share.

| Name | Type | Description |
| --- | --- | --- |
|recipients<sup>*required</sup>|Array&lt;<a href="#ssoentity" target="_blank" rel="noopener noreferrer">SsoEntity</a>&gt;|<p>An array of SSO entities (users and/or groups) to add to this share. They immediately get access to the document.</p> <p>Already added entities are ignored.</p>  |

### BulkDeleteRequest

| Name | Type | Description |
| --- | --- | --- |
|ids<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;|The ids of the documents that shall be deleted. Must not be empty. |

### BulkDeleteResponse

Result of the bulk operation for the individual objects.

| Name | Type |
| --- | --- |
|documents|Array&lt;<a href="#bulkdeleteresponsedocumentsitem">BulkDeleteResponseDocumentsItem</a>&gt;|

### BulkDeleteResponseDocumentsItem

| Name | Type | Description |
| --- | --- | --- |
|code<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|HTTP code the single delete endpoint would return for a request with this Document ID |
|error|<a href="#error" target="_blank" rel="noopener noreferrer">Error</a>|An error response as defined <a href="https://dt-url.net/platform-services-error-handling" target="_blank" rel="noopener noreferrer" >here</a>. |
|id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|ID of the document. |

### CreateDirectShare

Input required to create a direct-share.

| Name | Type | Description |
| --- | --- | --- |
|access<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Specifies which permissions shall be granted via the share: - <code>read</code> - grants permission to read the document, but not to update or delete it. - <code>read-write</code> - grants permission to read and update the document, but not to delete it. |
|documentId<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Document id. |
|recipients<sup>*required</sup>|Array&lt;<a href="#ssoentity">SsoEntity</a>&gt;|An array of sso-users (sso-ids). These users will immediately get access to the document. Can be empty. |

### CreateDocumentBody

| Name | Type | Description |
| --- | --- | --- |
|content<sup>*required</sup>|Blob &#124; Buffer &#124; Binary &#124; File|The binary content of this document. Its exact type is taken from the <code>Content-Type</code> header, which is thus mandatory. |
|description|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Optional description of this document. Maximum length is 256 characters. |
|~~externalId~~<sup>**DEPRECATED**</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p><strong>Deprecated</strong>. Use the <code>id</code> property instead.</p> <p>An optional user-provided id, in addition to the system-provided id. The following constraints apply:</p> <ul> <li>It must be unique in this environment</li> <li>Allowed characters: <code>A-Z</code> <code>a-z</code> <code>0-9</code> <code>-</code>.</li> <li>It must not be a UUID, however it can contain a UUID, so e.g. <code>my-e015739d-da78-4fe4-bef1-e95c2420bc25</code> is allowed, while <code>e015739d-da78-4fe4-bef1-e95c2420bc25</code> isn't allowed.</li> <li>Maximum length is 100 characters.</li> </ul>  |
|id|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>Optional. If provided, this will be the id of the document. If not provided, a system-generated id is used. The following constraints apply:</p> <ul> <li>It must be unique in this environment</li> <li>Allowed characters: <code>A-Z</code> <code>a-z</code> <code>0-9</code> <code>-</code>.</li> <li>It must not be a UUID, however it can contain a UUID, so e.g. <code>my-e015739d-da78-4fe4-bef1-e95c2420bc25</code> is allowed, while <code>e015739d-da78-4fe4-bef1-e95c2420bc25</code> isn't allowed.</li> <li>Maximum length is 100 characters.</li> </ul>  |
|name<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The name of this document. This name doesn't need to be unique and is <em>not</em> used as identifier. Maximum length is 128 characters. |
|type<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The type of this document. This type is <em>not</em> the Content-Type of the document, but instead adds a user-defined semantic. Maximum length is 128 characters. |

### CreateEnvShare

Input required to create a environment-share.

| Name | Type | Description |
| --- | --- | --- |
|access<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>Specifies which permissions shall be granted via the share:</p> <ul> <li><code>read</code> - grants permission to read the document, but not to update or delete it. - read-write` - grants permission to read and update the document, but not to delete it.</li> </ul>  |
|documentId<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Document id. |

### CreatedSnapshot

| Name | Type | Description |
| --- | --- | --- |
|snapshotVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|System-generated snapshot version. |

### CreationInfo

Info related to creation of the entity.

| Name | Type | Description |
| --- | --- | --- |
|createdBy<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|User who created this entity. |
|createdTime<sup>*required</sup>|Date|Creation time (in notation as defined by RFC 3339, section 5.6). |

### DeletionInfo

Info related to the deletion of the entity.

| Name | Type | Description |
| --- | --- | --- |
|deletedBy<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|User who deleted this entity. |
|deletedTime<sup>*required</sup>|Date|Time of deletion (in notation as defined by RFC 3339, section 5.6). |

### DirectShare

| Name | Type | Description |
| --- | --- | --- |
|access<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;|The access granted by this share. |
|documentId<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The shared document's id. |
|groupCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Number of groups which have been assigned to this share. |
|id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated id. |
|userCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Number of users who have been directly assigned to this share and therefore can access the document and collaborate on it. Not that potentially assigned groups and their users (see groupCount) are not reflected in this number. |

### DirectShareList

A list of direct-shares.

| Name | Type |
| --- | --- |
|direct-shares<sup>*required</sup>|Array&lt;<a href="#directshare" target="_blank" rel="noopener noreferrer">DirectShare</a>&gt;| 
|nextPageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)| 
|totalCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|

### DirectShareRecipientList

Envelope object for a list of recipients.

| Name | Type | Description |
| --- | --- | --- |
|nextPageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Use this as page-key query param to get the next page |
|recipients<sup>*required</sup>|Array&lt;<a href="#ssoentity">SsoEntity</a>&gt;| |
|totalCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Total number of recipients of the share. |

### DocumentList

Envelope object for a list of metadata

| Name | Type | Description |
| --- | --- | --- |
|documents<sup>*required</sup>|Array&lt;<a href="#documentmetadata" target="_blank" rel="noopener noreferrer">DocumentMetaData</a>&gt;| |
|nextPageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Use this as <code>page-key</code> query param to get the next page. If the list was paginated, and there are more results available, this parameter will be returned. |
|totalCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The total amount of matching results for this query, as if no pagination would have been applied. |

### DocumentLockDetails

The locking details of the document.

| Name | Type | Description |
| --- | --- | --- |
|documentVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Latest version of the document. |
|isLocked|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Document is locked or not. |
|isLockedByAnotherUser<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Document is locked by another user or not. |
|lockedBy|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The user that currently owns the lock. |

### DocumentMetaData

| Name | Type | Description |
| --- | --- | --- |
|access<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;|<p>Indicates which operations you may apply to this document. For example, if you own the document, this array contains the values \['read', 'write', 'delete'].</p> <ul> <li><code>read</code> - you may read, but not update or delete it.</li> <li><code>write</code> - you may update, but not read or delete it.</li> <li><code>delete</code> - you may delete, but not read or update it.</li> </ul>  |
|description|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Description, provided by the user. |
|~~externalId~~<sup>**DEPRECATED**</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|User-given id. Deprecated in favor of id. |
|id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated or user-given id of a document. |
|isPrivate<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether this document is public. Public documents can be read by every user of the environment. |
|isReshareable|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether users who have write access via shares may re-share the document with other users. Otherwise, only the owner may share the document with other users. |
|modificationInfo<sup>*required</sup>|<a href="#modificationinfo">ModificationInfo</a>|Info related to creation and modification of the entity. |
|name<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Name, provided by the user. The system is entirely agnostic of this value and there are no semantics attached to it. |
|originAppId|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The id of the application that shipped that document. Null, if the document isn't ready-made by an app. |
|originExtensionId|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The id of the extension that shipped that document. Null, if the document isn't shipped by an extension. |
|owner<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Unique user id derived from Authorization header. |
|shareInfo|<a href="#shareinfo" target="_blank" rel="noopener noreferrer">ShareInfo</a>|Share-specific information related to this document. |
|type<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Type, provided by the user. The system is entirely agnostic of this value and there are no semantics attached to it. |
|userContext|<a href="#usercontext">UserContext</a>|User-specific information related to this document. |
|version<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Initial value is 1. Every manipulation (of metadata or content) leads to an increment. This value is used for optimistic locking during modification operations. |

### EnvironmentShare

| Name | Type | Description |
| --- | --- | --- |
|access<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;|<p>Indicates which operations you may apply to this document. For example, if you own the document, this array contains the values \['read', 'write', 'delete'].</p> <ul> <li><code>read</code> - you may read, but not update or delete it.</li> <li><code>write</code> - you may update, but not read or delete it.</li> <li><code>delete</code> - you may delete, but not read or update it.</li> </ul>  |
|claimCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Number of users who have claimed this share and therefore can access the document and collaborate on it. |
|documentId<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The shared document's id. |
|id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|System-generated id of a share resource. |

### EnvironmentShareClaimResult

Confirmation of claiming an environment-share.

| Name | Type | Description |
| --- | --- | --- |
|access<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;|<p>Indicates which operations you may apply to this document. For example, if you own the document, this array contains the values \['read', 'write', 'delete'].</p> <ul> <li><code>read</code> - you may read, but not update or delete it.</li> <li><code>write</code> - you may update, but not read or delete it.</li> <li><code>delete</code> - you may delete, but not read or update it.</li> </ul>  |
|documentId<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The shared document's id. |
|documentType<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The shared document's type. |

### EnvironmentShareClaimerList

Envelope object for a list of claimers.

| Name | Type | Description |
| --- | --- | --- |
|claimers<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;| |
|nextPageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Use this as page-key query param to get the next page |
|totalCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The total amount of results for this query |

### EnvironmentShareList

A list of environment-shares.

| Name | Type | Description |
| --- | --- | --- |
|environment-shares<sup>*required</sup>|Array&lt;<a href="#environmentshare" target="_blank" rel="noopener noreferrer">EnvironmentShare</a>&gt;| |
|nextPageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Use this as <code>page-key</code> query param to get the next page. If the list was paginated, and there are more results available, this parameter will be returned. |
|totalCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The total amount of matching results for this query, as if no pagination would have been applied. |

### Error

An error response as defined [here](https://dt-url.net/platform-services-error-handling).

| Name | Type |
| --- | --- |
|code<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)| 
|details|<a href="#errordetails">ErrorDetails</a>| 
|message<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|

### ErrorDetails

| Name | Type |
| --- | --- |
|errorRef|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|

### ErrorEnvelope

| Name | Type | Description |
| --- | --- | --- |
|error<sup>*required</sup>|<a href="#error" target="_blank" rel="noopener noreferrer">Error</a>|An error response as defined <a href="https://dt-url.net/platform-services-error-handling" target="_blank" rel="noopener noreferrer" >here</a>. |

### GetDocumentResponse

| Name | Type | Description |
| --- | --- | --- |
|content|Binary|The binary content of this document. |
|metadata|<a href="#documentmetadata">DocumentMetaData</a>| |

### ModificationInfo

Info related to creation and modification of the entity.

| Name | Type | Description |
| --- | --- | --- |
|createdBy<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|User who created this entity. |
|createdTime<sup>*required</sup>|Date|Creation time (in notation as defined by RFC 3339, section 5.6). |
|lastModifiedBy<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|User who last modified this entity (metadata or content). |
|lastModifiedTime<sup>*required</sup>|Date|Time of last modification (in notation as defined by RFC 3339, section 5.6). |
|lastModifyingAppId|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Dynatrace app which last modified this entity's content. Null, if the last modification wasn't done by an app or if this property was not specifically requested via <code>add-fields</code>. |

### RemoveDirectShareRecipients

Input required to remove recipients from a direct-share.

| Name | Type |
| --- | --- |
|ids<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;|

### RestoreDocumentResult

| Name | Type |
| --- | --- |
|createdSnapshot|<a href="#createdsnapshot" target="_blank" rel="noopener noreferrer">CreatedSnapshot</a>| 
|documentMetadata<sup>*required</sup>|<a href="#documentmetadata">DocumentMetaData</a>|

### ShareInfo

Share-specific information related to this document.

| Name | Type | Description |
| --- | --- | --- |
|isShared|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Indicates whether the document is shared with at least one user. This means it's true if one of the following applies:</p> <ul> <li>The document is public</li> <li>There is at least one direct share with at least one user or group</li> <li>There is at least one environment share, regardless of how many users have claimed that share</li> </ul>  |
|isSharedWithCurrentUser|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether the document is shared with the user that has requested it. |

### SnapshotList

Envelope object for a list of snapshots of a document.

| Name | Type | Description |
| --- | --- | --- |
|nextPageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Use this as <code>page-key</code> query param to get the next page. If the list was paginated, and there are more results available, this parameter will be returned. |
|snapshots<sup>*required</sup>|Array&lt;<a href="#snapshotmetadata" target="_blank" rel="noopener noreferrer">SnapshotMetadata</a>&gt;| |
|totalCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The total amount of matching results for this query, as if no pagination would have been applied. |

### SnapshotMetadata

Metadata of a snapshot of a document.

| Name | Type | Description |
| --- | --- | --- |
|description|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|An optional description of the snapshot's content or the changes it introduces to the previous snapshot. Provided by the user or app. |
|documentVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The document version associated with this snapshot. The document had this version when the snapshot was created. |
|modificationInfo<sup>*required</sup>|<a href="#creationinfo">CreationInfo</a>|Info related to creation of the entity. |
|snapshotVersion<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>System-maintained auto-incremented snapshot version, starting at 1.</p> <p>This isn't the document version.</p>  |

### SsoEntity

A SSO user or SSO group.

| Name | Type | Description |
| --- | --- | --- |
|id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|SSO id of a user or group. |
|type<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Type of the SSO entity - either <code>user</code> or <code>group</code>. |

### TransferOwner

Input required to transfer document ownership.

| Name | Type | Description |
| --- | --- | --- |
|newOwnerId<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|SSO id of the new owner. |

### TrashDocument

A document which has been moved to the trash.

| Name | Type | Description |
| --- | --- | --- |
|deletionInfo<sup>*required</sup>|<a href="#deletioninfo" target="_blank" rel="noopener noreferrer">DeletionInfo</a>|Info related to the deletion of the entity. |
|id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Id of the deleted document. |
|modificationInfo<sup>*required</sup>|<a href="#modificationinfo">ModificationInfo</a>|Info related to creation and modification of the entity. |
|name<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Name of the deleted document. |
|owner<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Owner of the deleted document. |
|type<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Type of the deleted document. |
|version<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Version of the deleted document. |

### TrashDocumentList

Envelope object for a list of documents in trash.

| Name | Type | Description |
| --- | --- | --- |
|documents<sup>*required</sup>|Array&lt;<a href="#trashdocumentlistentry" target="_blank" rel="noopener noreferrer">TrashDocumentListEntry</a>&gt;| |
|nextPageKey|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Use this as <code>page-key</code> query param to get the next page. If the list was paginated, and there are more results available, this parameter will be returned. |
|totalCount<sup>*required</sup>|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The total amount of matching results for this query, as if no pagination would have been applied. |

### TrashDocumentListEntry

A document which has been deleted and now lives in the trash.

| Name | Type | Description |
| --- | --- | --- |
|deletionInfo<sup>*required</sup>|<a href="#deletioninfo">DeletionInfo</a>|Info related to the deletion of the entity. |
|id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Id of the deleted document. |
|name<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Name of the deleted document. |
|type<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Type of the deleted document. |

### UpdateDocumentBody

| Name | Type | Description |
| --- | --- | --- |
|content|Blob &#124; Buffer &#124; Binary &#124; File|<p>The binary content of this document. Its exact type is taken from the <code>Content-Type</code> header, which is thus mandatory. Optional - if not provided, no change happens.</p>  |
|description|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>Description of this document.</p> <p>Maximum length is 256 characters. Optional - if not provided, no change happens.</p>  |
|isPrivate|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Controls whether this document should be public. Public documents can be read by every user of the environment. This can only be changed by the document owner. Optional - if not provided, no change happens.</p>  |
|isReshareable|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>Controls whether users who receive write access via shares may re-share the document with other users. This can only be changed by the document owner. Optional - if not provided, no change happens.</p>  |
|name|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The name of this document. This name doesn't need to be unique and is <em>not</em> used as identifier.</p> <p>Maximum length is 128 characters. Optional - if not provided, no change happens.</p>  |
|snapshotDescription|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>An optional user-provided description of the snapshot's content or the changes it introduced.</p> <p>This description gets ignored if the query-param <code>create-snapshot</code> isn't set to true.</p> <p>Maximum length is 128 characters.</p>  |
|type|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The type of this document. This type is <em>not</em> the Content-Type of the document, but instead adds a user-defined semantic.</p> <p>Maximum length is 128 characters. Optional - if not provided, no change happens.</p>  |

### UpdateDocumentContentBody

| Name | Type |
| --- | --- |
|content<sup>*required</sup>|Blob &#124; Buffer &#124; Binary &#124; File|

### UpdateDocumentMetadata

| Name | Type |
| --- | --- |
|createdSnapshot|<a href="#createdsnapshot" target="_blank" rel="noopener noreferrer">CreatedSnapshot</a>| 
|documentMetadata<sup>*required</sup>|<a href="#documentmetadata">DocumentMetaData</a>|

### UpdateDocumentMetadataBody

| Name | Type | Description |
| --- | --- | --- |
|name|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Document name. |
|type|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Document type. |

### UserContext

User-specific information related to this document.

| Name | Type | Description |
| --- | --- | --- |
|lastAccessedTime|Date|Time when the current user last opened or modified this document (in notation as defined by RFC 3339, section 5.6). |