Create, update, list, organize, and secure Dynatrace Document API documents with metadata, content, snapshots, locks, favorites, labels, and access permissions.
Use the @dynatrace-sdk/client-document SDK client instead of calling this API directly — it handles authentication, typing, and the environment URL for you. This REST reference is for external and automation use.
This API allows you to create and manage documents, as well as manage access to them.
Have a look at the service documentation 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.
There are 2 different permission mechanisms. Most operations involve both mechanisms.
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.
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).
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.
Document ownership can be changed via the transferDocumentOwner operation.
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.
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.
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.
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.
All users with write access to a document may list, read, create, or restore its snapshots.
For built-in (App-Shipped or Extension) documents, listing snapshots returns an empty list rather than a 403, since these documents don't support snapshots.
Only the document owner (or an admin) may delete a snapshot.
Labels allow the user to organize and search their documents.
Labels are optional, a document may have zero or more. The maximum number of labels per document is 25 and the maximum length of each label is 80 characters.
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.
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.
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.
Users can mark documents as favorites for quick access. Favorites are personal — the favorite state is per-user and is not visible to the document's owner or other users.
A document can only be favorited if the user has at least read access to it.
Favoriting a document that is already a favorite is a no-op (idempotent). Removing a favorite that doesn't exist is equally a no-op.
Some documents are created and maintained by the system itself, instead of being user-owned.
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.
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.
Platform API endpoints use Platform token and OAuth client authentication. Attach a platform token or OAuth access token to the Authorization HTTP header using the Bearer scheme.
--header 'Authorization: Bearer <platform-token-or-oauth-access-token>'
For details, see Tokens and authentication and Platform tokens.
GET /documents)POST /documents)GET /documents/{id})DELETE /documents/{id})PATCH /documents/{id})GET /documents/{id}/metadata)PATCH /documents/{id}/metadata) DeprecatedGET /documents/{id}/content)PUT /documents/{id}/content)GET /documents/{id}/snapshots)GET /documents/{id}/snapshots/{snapshot-version})DELETE /documents/{id}/snapshots/{snapshot-version})POST /documents/{id}/snapshots/{snapshot-version}:restore)GET /documents/{id}:inspect-lock)POST /documents/{id}:acquire-lock)POST /documents/{id}:release-lock)POST /documents/{id}:transfer-owner)POST /documents/{id}:favorite)POST /documents/{id}:unfavorite)POST /documents/{id}:makePublic)POST /documents/{id}:makePrivate)GET /labels)GET /environment-shares)POST /environment-shares)GET /environment-shares/{id})DELETE /environment-shares/{id})PUT /environment-shares/{id}/claim)GET /environment-shares/{id}/claimers)GET /direct-shares)POST /direct-shares)GET /direct-shares/{id})DELETE /direct-shares/{id})GET /direct-shares/{id}/recipients)POST /direct-shares/{id}/recipients/add)POST /direct-shares/{id}/recipients/remove)GET /trash/documents)GET /trash/documents/{id})DELETE /trash/documents/{id})POST /trash/documents/{id}/restore)POST /documents:delete)