Endpoint Overview

All paths on this page are appended to the tenant's base URL:

https://<tenant>.stp-cloud.de/documents/dms-cloud-api/api

The base URL does not include a version number – that appears at the beginning of each path. The full URL for a case file search is therefore https://<tenant>.stp-cloud.de/documents/dms-cloud-api/api/v1/dms/documents/container. The advantage of this structure: URLs returned by the API itself – such as the statusUrl of an operation – can be appended to the base URL without modification.

Every request requires two scopes in the token: the tenant's license scope (dms.cloud.api.standalone or the corresponding partner-specific scope) and the endpoint's capability scope listed in the Required Scope column.

"Scope" here refers exactly to what is in the access token – the same strings that can be selected in the client registration under allowed scopes. If either one is missing, the request will be rejected; which one is missing is indicated by the error code (403 LICENSE_MISSING or 403 INSUFFICIENT_SCOPE respectively). For details, see Licenses and Permissions.

Case Files, Folders, and Documents

Versions and Renditions in Detail

A document can have multiple versions – each version is a distinct snapshot of the content, with the most recent being the current one. Each version may also have renditions: alternative representations of the same content, such as a PDF preview or a full-text extract.

In addition to title, comment, and document class, the master data also indicates how the document entered the document management system (source, e.g. bea or scan), whether it is inbound or outbound (mailRoute), the date of the letter – and whether a modification would currently be rejected (lockState). It is worth checking the latter before uploading a file: a locked document will not accept a new version.

Who created or last modified a document is deliberately not returned. The document management system stores user accounts belonging to your firm; the API returns timestamps, not names.

When uploading a new version, only the content changes: the case file, section, title, and document class remain as they are. The comment field describes the new version – unlike when importing a new document, it does not become the document's title. If comment is omitted, the comment from the previous version is carried over.

If the document is currently being edited by someone else, has been modified in the meantime, is frozen, or is marked for deletion, the operation will fail with errorCode: "CONFLICT". In that case, re-read the document and retry the request.

Things to note:

• Renditions can only be retrieved. This API provides no way to upload or delete a rendition; they are generated by the document management system itself – known names are stp.doc.preview (PDF preview) and stp.doc.fulltext.txt (full text).
• Without version, the latest version is used. Which version that was is included in the operation result.
• The API tells you which versions and renditions exist. The version history lists version numbers, and the renditions list provides names – both are exactly what ?version= and ?rendition= expect when retrieving content. If a number or name does not exist, the API responds with 404.
• The version history shows only the count of renditions per version, not their names – this keeps the response compact even when there are many versions. The names are returned by GET …/{documentId}/renditions.

Searching for Case Files and Folders in Detail

GET /v1/dms/documents/container supports four modes of operation. At most one of the three search parameters may be set at a time:

Each result includes an identifier, a display name, the firm's internal file reference number, the court file reference number, and the type (case file or folder) – along with accessLevel, indicating what the calling user is allowed to do with that case file (none, read, write, full). This lets you identify a read-only result before a write attempt fails. If the field is absent, the document management system is reporting a permission level that this API does not recognize – in that case, only the actual request will reveal what is permitted.

Parties associated with a case file – client, opposing party, case handler – are deliberately not returned by the API. This data is personal information, and no function of this API requires it.

File Uploads

These endpoints belong to the platform and are independent of the document management system. They generate time-limited, signed URLs; the file bytes do not pass through the API.

The multipart variant is intended for large files. For anything that can be transferred in a single request, uploads/single is sufficient.

Operations and System Status

Querying an operation requires exactly the same scope as the request that triggered it. A status check therefore never reveals more than the original request was permitted to access.

Checking the connector status requires its own scope (dms.cloud.api.connector.read), which is deliberately separate from the file upload scope: anyone who only wants to know whether the connector is running should not need write permission to do so. This scope must be explicitly assigned to the role – without it, the endpoint responds with 403 INSUFFICIENT_SCOPE, even if all other requests are working correctly.

Operation States

Which Requests Are Synchronous and Which Are Asynchronous

A 202 means accepted, not completed. The request is still validated immediately: a malformed request returns a 400 on that call and never becomes a failed operation.

Recommended Headers

There is no header for the tenant. The tenant is determined solely from the token.

Further Reading

• Quick Start
• Error Codes