# ConnectCloud DMS API (v1.0.0)

Documents with versions, links to records, text extraction, containers, compliance (audit, legal hold) and exports.

Base URLs:

- Production: `https://api.mbcom.cloud`
- Staging: `https://api.mbcom.cloud`
- Sandbox: `https://developers.mbcom.cloud/sandbox/dms`

The DMS ("Dokumentenmanagement") stores the documents of a tenant in an audit-proof way
(GoBD): every file is kept with its SHA-256 hash, every change creates a new immutable
version, every access and change is written to a hash-chained audit trail, and documents
cannot be deleted before their retention period has ended.

The public API lives under `/api/dms/v1`; the paths below are complete (server `/`), because
the service-to-service API of the module is mounted under `/internal`.

## Model
- A **document** is one stored file with its metadata: `title`, `fileName`, `mimeType`, a
  per-tenant, per-year `documentNumber` (`DOC-2026-000042`), a **document type** (`category`),
  `source` (`upload`, `mail`, `internal`, `api`), free JSON `metadata`, a `confidentialLevel`
  (`PUBLIC`, `INTERNAL` – the default –, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`) and
  `isPortalVisible`. Uploading a file whose SHA-256 already exists in the tenant returns the
  existing document (`duplicate: true`) instead of storing it twice.
- **Versions**: new content for a document is stored as a new version (`versionNumber` 1, 2, …);
  older versions stay readable. `currentVersion` is the latest.
- **Links** connect a document with records of other modules: `targetType` is one of
  `CUSTOMER`, `SUPPLIER`, `DISTRIBUTOR`, `ADDRESS`, `ARTICLE` (masterdata), `TRANSACTION`,
  `INVOICE`, `CONTRACT` (trade), `EMPLOYEE`, `TRAVEL_REPORT` (hr), `TICKET`, `WORK_ITEM` (desk), `FORGE_ITEM` (forge), `LEAD`,
  `OPPORTUNITY`, `CAMPAIGN` (crm), `PROJECT` (projects), `ASSET` (rmm); `targetModule` defaults accordingly. `relationType` is a free code
  (`[A-Z0-9_]{1,64}`, default `ATTACHMENT`). `STANDALONE` marks "no link" and is never stored.
- **Folders** file the documents of a tenant in a tree (at most 10 levels, 5,000 folders). A
  document is in at most one folder (`folderId`; none = „Ohne Ordner“), independent of its
  links. Moving a document changes neither content, hash nor retention; it is recorded in the
  audit trail (`FOLDER`). A folder with subfolders or documents cannot be deleted (`409`). A
  document type may name a **default folder**: uploads without `folderId` are filed there
  (`folderId=none` files nowhere).
- **Folder permissions:** a folder with access entries is restricted for its whole subtree.
  Entries name a person (`USER`, e-mail) or a DMS key group (`GROUP`) with `READ` or `WRITE`;
  a person needs an entry on every restricted folder above a document, and the weakest counts.
  Hidden folders and their documents do not exist for the caller (`404`, left out of lists);
  changes in a folder with `READ` answer `403` with `code: folder_read_only`.
  `tenant:dms:admin` is never restricted. Restricted documents are left out of search and of
  personal notifications; a flow starts on their events only when its owner may read the document.
- **Containers** group related documents, e.g. an e-mail (`EML` item) with its attachments
  (`ATTACHMENT` items); they have their own number (`CNT-2026-000007`).
- **Document types** (`Dokumentarten`) are tenant configuration: the allowed values of
  `category`, each with a retention period in years. New tenants start with `incoming_document`
  (Eingangsbeleg), `incoming_supplement` (Eingangsbeleg Zusatz), `delivery_note` (Lieferschein),
  `order_confirmation` (Auftragsbestätigung), `outgoing_invoice` (Ausgangsrechnung: the XRechnung
  of an invoice the tenant issued, filed by the trade module), `contract` (Vertrag),
  `correspondence` (Korrespondenz), `mail` (E-Mail-Original) and `other` (Sonstiges). Two
  **roles** name the type of the Original-Eingangsbeleg (`incoming_original`) and of its
  Zusatzbeleg (`incoming_supplement`) for the e-invoice integration; an upload may name the role
  (`documentRole`) instead of the type. Every upload of a user needs an active document type.
- **Retention and locking:** `retentionUntil` follows from the document type. A **WORM lock**
  (`isLocked`, `lockRetentionUntil`) can only be set or extended, never shortened. A **legal
  hold** blocks deletion regardless of retention. Deleting is a soft delete; the record, its
  hashes and its audit trail stay.
- **Text extraction:** every new version of an extractable file (PDF, images, TIFF, text,
  Markdown, CSV; office formats, HTML, XML and mails when the office converter is available) is
  queued for text extraction (text layer, OCR or e-invoice parsing). The state is the document's
  `extraction` object: `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL` (page limit or partial
  failure), `SKIPPED` or `FAILED` (with an `errorCode` such as `pdf_password`, `unsupported_type`,
  `too_large`, `no_text`, `upstream_unavailable`, `disabled`, `infected`). E-invoices are detected as
  `XRECHNUNG_CII`, `XRECHNUNG_UBL` or `ZUGFERD`.
- **Malware scan:** when the platform scans uploads, every new version starts as `scanStatus`
  `PENDING` and becomes `CLEAN`, `INFECTED` or – after repeated scanner errors – `FAILED`;
  encrypted uploads and versions without a scanner are `SKIPPED`. Content of `INFECTED` versions
  is never served (`403`, code `infected`). Only `CLEAN` content is served (encrypted content
  too, which cannot be scanned): `PENDING`, `FAILED` and `SKIPPED` content answers `409`, code
  `not_scanned` – a `FAILED` version is scanned again after an hour, a `SKIPPED` one as soon as a
  scanner runs. (Local development without a scanner serves everything but `INFECTED`.) Text
  extraction (and with it OCR and e-invoice import) waits for a `CLEAN` scan; an `INFECTED`
  version is never extracted (`extraction.status` `SKIPPED`, `errorCode` `infected`) and its file is
  left out of auditor exports (listed with `Infected` / `infected: true` in the index).
- **End-to-end encryption** (optional): the portal can encrypt a file in the browser
  (AES-256-GCM) and wrap the document key for users, key groups and the tenant's recovery key
  (ECDH P-256). The server stores ciphertext and wraps only, never decrypts, never extracts
  text and serves the content as `application/octet-stream`.
- Documents a platform module owns (`ownerModule`, e.g. desk ticket mails) follow that module's
  access rules and never appear in this API.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
| Permission | Grants |
|---|---|
| `tenant:dms:read` | list, read and download documents, versions, text, links, containers, audit trail and integrity checks; module configuration and status; register the own encryption key |
| `tenant:dms:write` | upload documents and versions, delete, lock, link and unlink, request text extraction, create containers, create, rename, move and delete folders and file documents in them |
| `tenant:dms:admin` | folder permissions, legal hold, tenant audit-chain check, auditor exports, tenant-wide re-extraction, key groups and the recovery key; may read the recovery wraps of encrypted documents |
| `tenant:settings:read` | read document types and their roles (also with `tenant:dms:read`) |
| `tenant:settings:write` | change document types, their order and roles; save the module configuration |

Missing permissions answer `403` with `{"error": "insufficient permissions", "code": "forbidden"}`.

## Conventions
- Lists answer `{items, total?, nextCursor?}`. The document list pages by cursor (`limit` 1–100, default 50, and
  `cursor` = the previous page's `nextCursor`), containers by `limit` and `offset`; the other lists are bounded and
  come whole with `total`. An invalid `limit`, `offset` or `cursor` is a `400 invalid`.
- Errors have the shape `{error, code, field?, details?}`. `error` is a message (German for
  validation and conflict messages meant for users). Invalid input is `400 invalid` with `field` and
  `details.fields` (one entry per invalid field with a German `message`); refused deletes carry
  `details.retentionUntil`, the text endpoint `details.status`. The codes are listed in the `Error` schema.
- Every content and text read is recorded in the audit trail (`VIEW` or `DOWNLOAD`); content
  is never served without that entry.
- Stored files are served with `X-Content-Type-Options: nosniff`, `Cache-Control: private,
  no-store`, the SHA-256 as `ETag` and – for anything but PDFs and raster images – a sandboxing
  `Content-Security-Policy`.
- Uploads are `multipart/form-data` with exactly one `file` part; form fields must come
  **before** the file part (fields after it are ignored). The default size limit is 25 MB per
  file (the operator may change it); larger files answer `413`.
- Uploads are idempotent by content: the same bytes return the existing document with status
  `200` and `duplicate: true`; requested links are added to it.

## Events
Published through the transactional outbox (not for documents a module owns):
`dms.document.created`, `dms.document.version_created`, `dms.document.linked`,
`dms.document.unlinked`, `dms.document.locked`, `dms.document.deleted`, `dms.document.filed`
(folder changed, also after a folder was renamed, moved or its permissions changed: `folderId`,
`folderPath`, `restricted`),
`dms.document.text_extracted` (with `classificationStatus` for classified Eingangsbelege and
`targetModule`, the module that processes documents of the document's type),
`dms.document.text_extraction_failed` (also with `targetModule`),
`dms.document.classified` (document classifier: `category`, `suggestedCategory`, `targetModule`,
`confidence`, `classificationSource` `ai|einvoice|manual`, `classificationStatus`, `final`; a
proposal waiting for review has `final: false` and `targetModule: none`),
`dms.document_type.updated` (`code`, `action` `upserted|deleted`, `by`) and
`dms.usage.recorded` (stored bytes). Document events carry `documentId`; link events also
`targetModule`, `targetType`, `targetId` and `relationType`; `dms.document.created` also carries
`folderId`, `folderPath` and `restricted` for filed documents. No event carries document text, and
events of encrypted documents carry no title or metadata.

# Documents

## List documents (tenant:dms:read)

`GET /api/dms/v1/documents`

Module: DMS · operationId: `listDocuments` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Newest first; with `search` ranked by relevance. `search` (alias `q`) combines a German
full-text search over title, file name and extracted text with substring matches on title,
file name and document number. Every document carries its links. Deleted documents are not
listed. Pages by cursor: pass `nextCursor` as `cursor` (with the same filter and `sort`) until it is missing;
`total` counts the whole filter.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `search` | query | string |  | Search text |
| `q` | query | string |  | Alias of `search` (used when `search` is empty) |
| `category` | query | string |  | Document type code (case-insensitive) |
| `source` | query | string |  | (one of `upload`, `mail`, `internal`, `api`) |
| `isLocked` | query | boolean |  | Only locked (`true`) or unlocked (`false`) documents |
| `targetType` | query | TargetType |  | Only documents linked to a record of this type; `STANDALONE` = documents without any link (one of `CUSTOMER`, `SUPPLIER`, `DISTRIBUTOR`, `ADDRESS`, `ARTICLE`, `TRANSACTION`, `INVOICE`, `CONTRACT`, `EMPLOYEE`, `TRAVEL_REPORT`, `TICKET`, `WORK_ITEM`, `FORGE_ITEM`, `LEAD`, `OPPORTUNITY`, `CAMPAIGN`, `PROJECT`, `ASSET`, `STANDALONE`) |
| `targetId` | query | string |  | With `targetType`: only documents linked to this record (max length 128) |
| `folderId` | query | string |  | Only documents in this folder; `none` = documents without a folder |
| `includeSubfolders` | query | boolean |  | With a `folderId`: also the documents of its subfolders (default `false`) |
| `containerId` | query | string (uuid) |  | Only the documents of this container |
| `sort` | query | string |  | Order (`-` = descending); default newest first, with `search` by relevance (one of `createdAt`, `-createdAt`, `title`, `-title`, `documentNumber`, `-documentNumber`) |
| `limit` | query | integer |  | Page size; another value than 1–100 is a `400 invalid` (`field: limit`) (default `50`; max 100) |
| `cursor` | query | string |  | `nextCursor` of the previous page (opaque); a cursor of another `sort` or an altered one is a `400 invalid` (`field: cursor`) |

### Responses

- **200** A page of documents (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Document, required): Documents of the page
  - `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
  - `createdAt` (string (date-time), required): Upload time
  - `currentVersion` (integer, required): Current version number
  - `customerNo` (string, required): Customer number of the tenant
  - `documentNumber` (string, required): Per-tenant, per-year document number
  - `extraction` (Extraction, required): Text extraction state of the current version
    - `attempts` (integer, required): Extraction attempts so far
    - `degraded` (boolean, required): At least one page was extracted in degraded quality
    - `pagesProcessed` (integer, required): Pages extracted so far
    - `pagesTotal` (integer, required): Pages of the file
    - `status` (ExtractionStatus, required)
    - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
    - `error` (string): Error message of a failed extraction
    - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
    - `updatedAt` (string (date-time)): Time of the last state change
  - `fileName` (string, required): File name of the current version
  - `fileSize` (integer (int64), required): Size of the current version
  - `id` (string (uuid), required): Document id
  - `isArchived` (boolean, required): Same as `isLocked`
  - `isEncrypted` (boolean, required): Content is client-side encrypted
  - `isLocked` (boolean, required): WORM lock (same as `isArchived`)
  - `isPortalVisible` (boolean, required): Visible in the customer portal
  - `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
  - `mimeType` (string, required): MIME type of the current version
  - `retentionYears` (integer, required): Retention period in years (from the document type)
  - `s3Bucket` (string, required): Storage bucket of the current version
  - `s3Key` (string, required): Storage key of the current version
  - `s3Path` (string, required): Same as `s3Key`
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
  - `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
  - `tenantName` (string, required): Tenant name
  - `title` (string, required): Defaults to the file name
  - `updatedAt` (string (date-time), required): Time of the last change
  - `uploadedBy` (string, required): Who uploaded the document
  - `version` (integer, required): Current version number (same as `currentVersion`)
  - `category` (string): Document type code
  - `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
  - `deletedAt` (string (date-time)): Time of the soft delete
  - `encryptionAlgorithm` (string): Only for encrypted documents
  - `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
  - `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
    - `id` (string (uuid), required): Folder id
    - `name` (string, required): Folder name
  - `hashSha256` (string): SHA-256 (hex) of the current version
  - `links` (array of DocumentLink): Omitted when the document has none
    - `createdAt` (string (date-time), required): Creation time
    - `createdBy` (string, required): Who created the link
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): The linked document
    - `id` (string (uuid), required): Link id
    - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
    - `targetId` (string, required): Id of the linked record
    - `targetModule` (string, required): Module of the linked record
    - `targetType` (string, required): Type of the linked record (see TargetType)
    - `tenantName` (string, required): Tenant name
  - `lockRetentionUntil` (string (date-time)): End of the WORM lock
  - `metadata` (object): Free metadata (JSON object)
  - `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
  - `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
  - `versions` (array of DocumentVersion): Only in the detail and after a version upload
    - `createdAt` (string (date-time), required): Upload time
    - `createdBy` (string, required): Who uploaded the version
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): The document of the version
    - `fileName` (string, required): File name of the version
    - `fileSize` (integer (int64), required): Size in bytes
    - `id` (string (uuid), required): Version id
    - `mimeType` (string, required): MIME type of the version
    - `s3Path` (string, required): Storage key of the version
    - `scanStatus` (ScanStatus, required)
    - `sha256Hash` (string, required): SHA-256 (hex) of the version
    - `tenantName` (string, required): Tenant name
    - `versionNumber` (integer, required): Version number, from 1
    - `changeSummary` (string): What changed with this version
- `total` (integer, required): Documents of the whole filter
- `nextCursor` (string): Cursor of the next page; missing on the last page

Example 200 answer:

```json
{
  "items": [
    {
      "category": "incoming_document",
      "classificationStatus": "classified",
      "confidentialLevel": "INTERNAL",
      "createdAt": "2026-09-30T08:40:12Z",
      "currentVersion": 1,
      "customerNo": "99999",
      "documentNumber": "DOC-2026-000042",
      "extraction": {
        "attempts": 1,
        "degraded": false,
        "eInvoice": "ZUGFERD",
        "pagesProcessed": 2,
        "pagesTotal": 2,
        "status": "DONE",
        "updatedAt": "2026-09-30T08:41:03Z"
      },
      "fileName": "RE-482117.pdf",
      "fileSize": 184320,
      "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
      "folderPath": [
        {
          "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
          "name": "Buchhaltung"
        },
        {
          "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
          "name": "Eingangsrechnungen 2026"
        }
      ],
      "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
      "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "isArchived": true,
      "isEncrypted": false,
      "isLocked": true,
      "isPortalVisible": false,
      "legalHold": false,
      "links": [
        {
          "createdAt": "2026-09-30T08:40:12Z",
          "createdBy": "christina.adler@muster-it.example",
          "customerNo": "99999",
          "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
          "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
          "relationType": "ATTACHMENT",
          "targetId": "70001",
          "targetModule": "masterdata",
          "targetType": "SUPPLIER",
          "tenantName": "DEMO"
        }
      ],
      "lockRetentionUntil": "2036-12-31T23:59:59Z",
      "metadata": {
        "invoiceNumber": "RE-482117",
        "supplier": "Nordlicht IT-Distribution GmbH"
      },
      "mimeType": "application/pdf",
      "retentionUntil": "2036-12-31T23:59:59Z",
      "retentionYears": 10,
      "s3Bucket": "99999-demo-prod-mbcom-cloud",
      "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
      "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
      "scanStatus": "CLEAN",
      "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
      "sizeBytes": 184320,
      "source": "mail",
      "tenantName": "DEMO",
      "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
      "updatedAt": "2026-09-30T08:41:03Z",
      "uploadedBy": "christina.adler@muster-it.example",
      "version": 1
    }
  ],
  "nextCursor": "eyJjIjoiMjAyNi0wOS0zMFQwODo0MDoxMloiLCJpZCI6IjNmNmMyYTFlIn0",
  "total": 128
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Upload a document (tenant:dms:write)

`POST /api/dms/v1/documents`

Module: DMS · operationId: `createDocument` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

The same upload as `POST /api/dms/v1/documents/upload` (`201` new, `200` duplicate, body
`UploadResult`). Only `multipart/form-data` is accepted: any other body is `415`
`multipart_required` (the former JSON variant, which registered an already stored file by
`s3Bucket`/`s3Key`, was removed – a document only points at a file DMS stored itself).

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required): The file (exactly one)
- `category` (string): Active document type code (required unless `documentRole` is given)
- `confidentialLevel` (ConfidentialLevel): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
- `documentRole` (string): Files the document under the type assigned to the role when no `category` is given (one of `incoming_original`, `incoming_supplement`)
- `encryption` (string): JSON `EncryptionInput`; the file part is then the ciphertext
- `extractText` (boolean): `true` forces, `false` disables text extraction; by default every extractable format is queued
- `folderId` (string): Files the new document in this folder (`400` when unknown, `403` when read-only); `none` = no folder; omitted = the default folder of the document type (if the caller may write there). A duplicate keeps its folder.
- `isEncrypted` (boolean): Marks a client-encrypted upload; requires `encryption`
- `isLocked` (boolean): Lock the document (WORM) on upload
- `isPortalVisible` (boolean): Visible in the customer portal (default `false`)
- `links` (string): JSON array of `LinkInput` (at most 50 links per upload, together with `targetType`)
- `lockRetentionDays` (integer): With `isLocked`, lock for this many days from now
- `metadata` (string): JSON object
- `mimeType` (string): Plaintext MIME type of an encrypted upload
- `relationType` (string): With `targetType`
- `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`; default `"upload"`)
- `targetId` (string): With `targetType`, the record to link
- `targetModule` (string): With `targetType`
- `targetType` (TargetType): Type of the linked record (case-insensitive); `STANDALONE` = no link (one of `CUSTOMER`, `SUPPLIER`, `DISTRIBUTOR`, `ADDRESS`, `ARTICLE`, `TRANSACTION`, `INVOICE`, `CONTRACT`, `EMPLOYEE`, `TRAVEL_REPORT`, `TICKET`, `WORK_ITEM`, `FORGE_ITEM`, `LEAD`, `OPPORTUNITY`, `CAMPAIGN`, `PROJECT`, `ASSET`, `STANDALONE`)
- `title` (string): Defaults to the file name

### Responses

- **200** The file already existed; the existing document is returned (`application/json`)
- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **413** Error (`application/json`)
- **415** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `document` (Document, required)
  - `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
  - `createdAt` (string (date-time), required): Upload time
  - `currentVersion` (integer, required): Current version number
  - `customerNo` (string, required): Customer number of the tenant
  - `documentNumber` (string, required): Per-tenant, per-year document number
  - `extraction` (Extraction, required): Text extraction state of the current version
    - `attempts` (integer, required): Extraction attempts so far
    - `degraded` (boolean, required): At least one page was extracted in degraded quality
    - `pagesProcessed` (integer, required): Pages extracted so far
    - `pagesTotal` (integer, required): Pages of the file
    - `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)
    - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
    - `error` (string): Error message of a failed extraction
    - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
    - `updatedAt` (string (date-time)): Time of the last state change
  - `fileName` (string, required): File name of the current version
  - `fileSize` (integer (int64), required): Size of the current version
  - `id` (string (uuid), required): Document id
  - `isArchived` (boolean, required): Same as `isLocked`
  - `isEncrypted` (boolean, required): Content is client-side encrypted
  - `isLocked` (boolean, required): WORM lock (same as `isArchived`)
  - `isPortalVisible` (boolean, required): Visible in the customer portal
  - `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
  - `mimeType` (string, required): MIME type of the current version
  - `retentionYears` (integer, required): Retention period in years (from the document type)
  - `s3Bucket` (string, required): Storage bucket of the current version
  - `s3Key` (string, required): Storage key of the current version
  - `s3Path` (string, required): Same as `s3Key`
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
  - `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
  - `tenantName` (string, required): Tenant name
  - `title` (string, required): Defaults to the file name
  - `updatedAt` (string (date-time), required): Time of the last change
  - `uploadedBy` (string, required): Who uploaded the document
  - `version` (integer, required): Current version number (same as `currentVersion`)
  - `category` (string): Document type code
  - `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
  - `deletedAt` (string (date-time)): Time of the soft delete
  - `encryptionAlgorithm` (string): Only for encrypted documents
  - `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
  - `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
    - `id` (string (uuid), required): Folder id
    - `name` (string, required): Folder name
  - `hashSha256` (string): SHA-256 (hex) of the current version
  - `links` (array of DocumentLink): Omitted when the document has none
    - `createdAt` (string (date-time), required): Creation time
    - `createdBy` (string, required): Who created the link
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): The linked document
    - `id` (string (uuid), required): Link id
    - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
    - `targetId` (string, required): Id of the linked record
    - `targetModule` (string, required): Module of the linked record
    - `targetType` (string, required): Type of the linked record (see TargetType)
    - `tenantName` (string, required): Tenant name
  - `lockRetentionUntil` (string (date-time)): End of the WORM lock
  - `metadata` (object): Free metadata (JSON object)
  - `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
  - `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
  - `versions` (array of DocumentVersion): Only in the detail and after a version upload
    - `createdAt` (string (date-time), required): Upload time
    - `createdBy` (string, required): Who uploaded the version
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): The document of the version
    - `fileName` (string, required): File name of the version
    - `fileSize` (integer (int64), required): Size in bytes
    - `id` (string (uuid), required): Version id
    - `mimeType` (string, required): MIME type of the version
    - `s3Path` (string, required): Storage key of the version
    - `scanStatus` (ScanStatus, required)
    - `sha256Hash` (string, required): SHA-256 (hex) of the version
    - `tenantName` (string, required): Tenant name
    - `versionNumber` (integer, required): Version number, from 1
    - `changeSummary` (string): What changed with this version
- `duplicate` (boolean, required): The tenant already had a document with the same content; it is returned instead

Example 201 answer:

```json
{
  "document": {
    "category": "incoming_document",
    "classificationStatus": "classified",
    "confidentialLevel": "INTERNAL",
    "createdAt": "2026-09-30T08:40:12Z",
    "currentVersion": 1,
    "customerNo": "99999",
    "documentNumber": "DOC-2026-000042",
    "extraction": {
      "attempts": 1,
      "degraded": false,
      "eInvoice": "ZUGFERD",
      "pagesProcessed": 2,
      "pagesTotal": 2,
      "status": "DONE",
      "updatedAt": "2026-09-30T08:41:03Z"
    },
    "fileName": "RE-482117.pdf",
    "fileSize": 184320,
    "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
    "folderPath": [
      {
        "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
        "name": "Buchhaltung"
      },
      {
        "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
        "name": "Eingangsrechnungen 2026"
      }
    ],
    "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
    "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
    "isArchived": true,
    "isEncrypted": false,
    "isLocked": true,
    "isPortalVisible": false,
    "legalHold": false,
    "links": [
      {
        "createdAt": "2026-09-30T08:40:12Z",
        "createdBy": "christina.adler@muster-it.example",
        "customerNo": "99999",
        "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
        "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
        "relationType": "ATTACHMENT",
        "targetId": "70001",
        "targetModule": "masterdata",
        "targetType": "SUPPLIER",
        "tenantName": "DEMO"
      }
    ],
    "lockRetentionUntil": "2036-12-31T23:59:59Z",
    "metadata": {
      "invoiceNumber": "RE-482117",
      "supplier": "Nordlicht IT-Distribution GmbH"
    },
    "mimeType": "application/pdf",
    "retentionUntil": "2036-12-31T23:59:59Z",
    "retentionYears": 10,
    "s3Bucket": "99999-demo-prod-mbcom-cloud",
    "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
    "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
    "scanStatus": "CLEAN",
    "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
    "sizeBytes": 184320,
    "source": "mail",
    "tenantName": "DEMO",
    "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
    "updatedAt": "2026-09-30T08:41:03Z",
    "uploadedBy": "christina.adler@muster-it.example",
    "version": 1
  },
  "duplicate": false
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```

## Upload a document (tenant:dms:write)

`POST /api/dms/v1/documents/upload`

Module: DMS · operationId: `uploadDocument` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores one file (`file` part) with its metadata. Put all form fields before the file part.
A document type is required: `category` (an active type code) or `documentRole`. The SHA-256
of the content is checked first: if the tenant already has the same unencrypted file, the
existing document is returned with `200` and `duplicate: true` (links requested in the
upload are added to it). The MIME type is detected from the part's `Content-Type`, the file
name and the content. Extractable formats are queued for text extraction unless
`extractText=false`; with a malware scanner the new version starts as `scanStatus: PENDING`.

Size limit: 25 MB per file by default (configurable by the operator); `413` beyond.

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required): The file (exactly one)
- `category` (string): Active document type code (required unless `documentRole` is given)
- `confidentialLevel` (ConfidentialLevel): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
- `documentRole` (string): Files the document under the type assigned to the role when no `category` is given (one of `incoming_original`, `incoming_supplement`)
- `encryption` (string): JSON `EncryptionInput`; the file part is then the ciphertext
- `extractText` (boolean): `true` forces, `false` disables text extraction; by default every extractable format is queued
- `folderId` (string): Files the new document in this folder (`400` when unknown, `403` when read-only); `none` = no folder; omitted = the default folder of the document type (if the caller may write there). A duplicate keeps its folder.
- `isEncrypted` (boolean): Marks a client-encrypted upload; requires `encryption`
- `isLocked` (boolean): Lock the document (WORM) on upload
- `isPortalVisible` (boolean): Visible in the customer portal (default `false`)
- `links` (string): JSON array of `LinkInput` (at most 50 links per upload, together with `targetType`)
- `lockRetentionDays` (integer): With `isLocked`, lock for this many days from now
- `metadata` (string): JSON object
- `mimeType` (string): Plaintext MIME type of an encrypted upload
- `relationType` (string): With `targetType`
- `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`; default `"upload"`)
- `targetId` (string): With `targetType`, the record to link
- `targetModule` (string): With `targetType`
- `targetType` (TargetType): Type of the linked record (case-insensitive); `STANDALONE` = no link (one of `CUSTOMER`, `SUPPLIER`, `DISTRIBUTOR`, `ADDRESS`, `ARTICLE`, `TRANSACTION`, `INVOICE`, `CONTRACT`, `EMPLOYEE`, `TRAVEL_REPORT`, `TICKET`, `WORK_ITEM`, `FORGE_ITEM`, `LEAD`, `OPPORTUNITY`, `CAMPAIGN`, `PROJECT`, `ASSET`, `STANDALONE`)
- `title` (string): Defaults to the file name

### Responses

- **200** The file already existed; the existing document is returned (`application/json`)
- **201** Stored (`application/json`)
- **400** Error (`application/json`)
- **413** Error (`application/json`)
- **415** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `document` (Document, required)
  - `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
  - `createdAt` (string (date-time), required): Upload time
  - `currentVersion` (integer, required): Current version number
  - `customerNo` (string, required): Customer number of the tenant
  - `documentNumber` (string, required): Per-tenant, per-year document number
  - `extraction` (Extraction, required): Text extraction state of the current version
    - `attempts` (integer, required): Extraction attempts so far
    - `degraded` (boolean, required): At least one page was extracted in degraded quality
    - `pagesProcessed` (integer, required): Pages extracted so far
    - `pagesTotal` (integer, required): Pages of the file
    - `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)
    - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
    - `error` (string): Error message of a failed extraction
    - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
    - `updatedAt` (string (date-time)): Time of the last state change
  - `fileName` (string, required): File name of the current version
  - `fileSize` (integer (int64), required): Size of the current version
  - `id` (string (uuid), required): Document id
  - `isArchived` (boolean, required): Same as `isLocked`
  - `isEncrypted` (boolean, required): Content is client-side encrypted
  - `isLocked` (boolean, required): WORM lock (same as `isArchived`)
  - `isPortalVisible` (boolean, required): Visible in the customer portal
  - `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
  - `mimeType` (string, required): MIME type of the current version
  - `retentionYears` (integer, required): Retention period in years (from the document type)
  - `s3Bucket` (string, required): Storage bucket of the current version
  - `s3Key` (string, required): Storage key of the current version
  - `s3Path` (string, required): Same as `s3Key`
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
  - `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
  - `tenantName` (string, required): Tenant name
  - `title` (string, required): Defaults to the file name
  - `updatedAt` (string (date-time), required): Time of the last change
  - `uploadedBy` (string, required): Who uploaded the document
  - `version` (integer, required): Current version number (same as `currentVersion`)
  - `category` (string): Document type code
  - `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
  - `deletedAt` (string (date-time)): Time of the soft delete
  - `encryptionAlgorithm` (string): Only for encrypted documents
  - `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
  - `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
    - `id` (string (uuid), required): Folder id
    - `name` (string, required): Folder name
  - `hashSha256` (string): SHA-256 (hex) of the current version
  - `links` (array of DocumentLink): Omitted when the document has none
    - `createdAt` (string (date-time), required): Creation time
    - `createdBy` (string, required): Who created the link
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): The linked document
    - `id` (string (uuid), required): Link id
    - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
    - `targetId` (string, required): Id of the linked record
    - `targetModule` (string, required): Module of the linked record
    - `targetType` (string, required): Type of the linked record (see TargetType)
    - `tenantName` (string, required): Tenant name
  - `lockRetentionUntil` (string (date-time)): End of the WORM lock
  - `metadata` (object): Free metadata (JSON object)
  - `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
  - `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
  - `versions` (array of DocumentVersion): Only in the detail and after a version upload
    - `createdAt` (string (date-time), required): Upload time
    - `createdBy` (string, required): Who uploaded the version
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): The document of the version
    - `fileName` (string, required): File name of the version
    - `fileSize` (integer (int64), required): Size in bytes
    - `id` (string (uuid), required): Version id
    - `mimeType` (string, required): MIME type of the version
    - `s3Path` (string, required): Storage key of the version
    - `scanStatus` (ScanStatus, required)
    - `sha256Hash` (string, required): SHA-256 (hex) of the version
    - `tenantName` (string, required): Tenant name
    - `versionNumber` (integer, required): Version number, from 1
    - `changeSummary` (string): What changed with this version
- `duplicate` (boolean, required): The tenant already had a document with the same content; it is returned instead

Example 201 answer:

```json
{
  "document": {
    "category": "incoming_document",
    "classificationStatus": "classified",
    "confidentialLevel": "INTERNAL",
    "createdAt": "2026-09-30T08:40:12Z",
    "currentVersion": 1,
    "customerNo": "99999",
    "documentNumber": "DOC-2026-000042",
    "extraction": {
      "attempts": 1,
      "degraded": false,
      "eInvoice": "ZUGFERD",
      "pagesProcessed": 2,
      "pagesTotal": 2,
      "status": "DONE",
      "updatedAt": "2026-09-30T08:41:03Z"
    },
    "fileName": "RE-482117.pdf",
    "fileSize": 184320,
    "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
    "folderPath": [
      {
        "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
        "name": "Buchhaltung"
      },
      {
        "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
        "name": "Eingangsrechnungen 2026"
      }
    ],
    "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
    "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
    "isArchived": true,
    "isEncrypted": false,
    "isLocked": true,
    "isPortalVisible": false,
    "legalHold": false,
    "links": [
      {
        "createdAt": "2026-09-30T08:40:12Z",
        "createdBy": "christina.adler@muster-it.example",
        "customerNo": "99999",
        "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
        "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
        "relationType": "ATTACHMENT",
        "targetId": "70001",
        "targetModule": "masterdata",
        "targetType": "SUPPLIER",
        "tenantName": "DEMO"
      }
    ],
    "lockRetentionUntil": "2036-12-31T23:59:59Z",
    "metadata": {
      "invoiceNumber": "RE-482117",
      "supplier": "Nordlicht IT-Distribution GmbH"
    },
    "mimeType": "application/pdf",
    "retentionUntil": "2036-12-31T23:59:59Z",
    "retentionYears": 10,
    "s3Bucket": "99999-demo-prod-mbcom-cloud",
    "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
    "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
    "scanStatus": "CLEAN",
    "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
    "sizeBytes": 184320,
    "source": "mail",
    "tenantName": "DEMO",
    "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
    "updatedAt": "2026-09-30T08:41:03Z",
    "uploadedBy": "christina.adler@muster-it.example",
    "version": 1
  },
  "duplicate": false
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/upload' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```

## A document with its links, versions and extraction state (tenant:dms:read)

`GET /api/dms/v1/documents/{id}`

Module: DMS · operationId: `getDocument` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Document (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
- `createdAt` (string (date-time), required): Upload time
- `currentVersion` (integer, required): Current version number
- `customerNo` (string, required): Customer number of the tenant
- `documentNumber` (string, required): Per-tenant, per-year document number
- `extraction` (Extraction, required): Text extraction state of the current version
  - `attempts` (integer, required): Extraction attempts so far
  - `degraded` (boolean, required): At least one page was extracted in degraded quality
  - `pagesProcessed` (integer, required): Pages extracted so far
  - `pagesTotal` (integer, required): Pages of the file
  - `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)
  - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
  - `error` (string): Error message of a failed extraction
  - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
  - `updatedAt` (string (date-time)): Time of the last state change
- `fileName` (string, required): File name of the current version
- `fileSize` (integer (int64), required): Size of the current version
- `id` (string (uuid), required): Document id
- `isArchived` (boolean, required): Same as `isLocked`
- `isEncrypted` (boolean, required): Content is client-side encrypted
- `isLocked` (boolean, required): WORM lock (same as `isArchived`)
- `isPortalVisible` (boolean, required): Visible in the customer portal
- `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
- `mimeType` (string, required): MIME type of the current version
- `retentionYears` (integer, required): Retention period in years (from the document type)
- `s3Bucket` (string, required): Storage bucket of the current version
- `s3Key` (string, required): Storage key of the current version
- `s3Path` (string, required): Same as `s3Key`
- `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
- `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
- `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
- `tenantName` (string, required): Tenant name
- `title` (string, required): Defaults to the file name
- `updatedAt` (string (date-time), required): Time of the last change
- `uploadedBy` (string, required): Who uploaded the document
- `version` (integer, required): Current version number (same as `currentVersion`)
- `category` (string): Document type code
- `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
- `deletedAt` (string (date-time)): Time of the soft delete
- `encryptionAlgorithm` (string): Only for encrypted documents
- `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
- `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name
- `hashSha256` (string): SHA-256 (hex) of the current version
- `links` (array of DocumentLink): Omitted when the document has none
  - `createdAt` (string (date-time), required): Creation time
  - `createdBy` (string, required): Who created the link
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The linked document
  - `id` (string (uuid), required): Link id
  - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
  - `targetId` (string, required): Id of the linked record
  - `targetModule` (string, required): Module of the linked record
  - `targetType` (string, required): Type of the linked record (see TargetType)
  - `tenantName` (string, required): Tenant name
- `lockRetentionUntil` (string (date-time)): End of the WORM lock
- `metadata` (object): Free metadata (JSON object)
- `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
- `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
- `versions` (array of DocumentVersion): Only in the detail and after a version upload
  - `createdAt` (string (date-time), required): Upload time
  - `createdBy` (string, required): Who uploaded the version
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The document of the version
  - `fileName` (string, required): File name of the version
  - `fileSize` (integer (int64), required): Size in bytes
  - `id` (string (uuid), required): Version id
  - `mimeType` (string, required): MIME type of the version
  - `s3Path` (string, required): Storage key of the version
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): SHA-256 (hex) of the version
  - `tenantName` (string, required): Tenant name
  - `versionNumber` (integer, required): Version number, from 1
  - `changeSummary` (string): What changed with this version

Example 200 answer:

```json
{
  "category": "incoming_document",
  "classificationStatus": "classified",
  "confidentialLevel": "INTERNAL",
  "createdAt": "2026-09-30T08:40:12Z",
  "currentVersion": 1,
  "customerNo": "99999",
  "documentNumber": "DOC-2026-000042",
  "extraction": {
    "attempts": 1,
    "degraded": false,
    "eInvoice": "ZUGFERD",
    "pagesProcessed": 2,
    "pagesTotal": 2,
    "status": "DONE",
    "updatedAt": "2026-09-30T08:41:03Z"
  },
  "fileName": "RE-482117.pdf",
  "fileSize": 184320,
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "folderPath": [
    {
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung"
    },
    {
      "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
      "name": "Eingangsrechnungen 2026"
    }
  ],
  "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "isArchived": true,
  "isEncrypted": false,
  "isLocked": true,
  "isPortalVisible": false,
  "legalHold": false,
  "links": [
    {
      "createdAt": "2026-09-30T08:40:12Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
      "relationType": "ATTACHMENT",
      "targetId": "70001",
      "targetModule": "masterdata",
      "targetType": "SUPPLIER",
      "tenantName": "DEMO"
    }
  ],
  "lockRetentionUntil": "2036-12-31T23:59:59Z",
  "metadata": {
    "invoiceNumber": "RE-482117",
    "supplier": "Nordlicht IT-Distribution GmbH"
  },
  "mimeType": "application/pdf",
  "retentionUntil": "2036-12-31T23:59:59Z",
  "retentionYears": 10,
  "s3Bucket": "99999-demo-prod-mbcom-cloud",
  "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "scanStatus": "CLEAN",
  "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "sizeBytes": 184320,
  "source": "mail",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
  "updatedAt": "2026-09-30T08:41:03Z",
  "uploadedBy": "christina.adler@muster-it.example",
  "version": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete a document (tenant:dms:write)

`DELETE /api/dms/v1/documents/{id}`

Module: DMS · operationId: `deleteDocument` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Soft delete: the document disappears from the API, its record, hashes and audit trail stay
(GoBD) and the files are purged later. Refused with `409` while the document is under legal
hold, under an active WORM lock, or its retention period (`retentionUntil`) has not ended.
The optional body records a reason in the audit trail.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `reason` (string): Recorded in the audit trail

Example:

```json
{
  "reason": "Doppelt erfasst"
}
```

### Responses

- **204** Deleted
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Doppelt erfasst"}'
```

## The file of the current version (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/content`

Module: DMS · operationId: `getDocumentContent` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Streams the stored file with its MIME type, inline by default, as attachment with
`download=true` (audited as `VIEW` or `DOWNLOAD`). Encrypted documents are always served as
attachment with `Content-Type: application/octet-stream` and `X-Encryption-Algorithm:
AES-256-GCM`; decrypt them with the envelope from `getDocumentEncryption`. Infected files
answer `403` with `code: infected`; encrypted documents without a key for the caller answer
`403`; a file the malware scan has not cleared yet answers `409` with `code: not_scanned`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `download` | query | boolean |  | `true` serves the file as attachment (default `false`) |

### Responses

- **200** The stored file with its MIME type (`*/*`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/content' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The file of the current version, inline (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/preview`

Module: DMS · operationId: `previewDocument` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Like `getDocumentContent`, always with `Content-Disposition: inline` (encrypted documents still as attachment). Audited as `VIEW`; same errors (`403 infected`, `409 not_scanned`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The stored file with its MIME type (`*/*`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Download descriptor or the file as attachment (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/download`

Module: DMS · operationId: `downloadDocument` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Without `stream` it returns a JSON descriptor (file name, type, size, hash and the
`downloadUrl`). With `stream=true` it streams the current version as attachment, audited as
`DOWNLOAD` (same headers and errors as `getDocumentContent`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `stream` | query | boolean |  | `true` streams the file instead of the descriptor (default `false`) |

### Responses

- **200** Descriptor (JSON) or, with `stream=true`, the file (`application/json`)
- **403** With `stream=true`: `infected`, or an encrypted document without a key for the caller (`application/json`)
- **404** Error (`application/json`)
- **409** With `stream=true`: `not_scanned` – the malware scan has not cleared the file yet (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `documentId` (string (uuid)): Document id
- `downloadUrl` (string): Path that streams the file
- `fileName` (string): File name of the current version
- `fileSize` (integer (int64)): Size in bytes
- `mimeType` (string): MIME type of the current version
- `sha256Hash` (string): SHA-256 (hex) of the current version

Example 200 answer:

```json
{
  "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "downloadUrl": "/api/dms/v1/documents/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/download?stream=true",
  "fileName": "RE-482117.pdf",
  "fileSize": 184320,
  "mimeType": "application/pdf",
  "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/download' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Versions

## The versions of a document, newest first (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/versions`

Module: DMS · operationId: `listDocumentVersions` · Tag: Versions · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Versions (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of DocumentVersion, required): The versions, newest first
  - `createdAt` (string (date-time), required): Upload time
  - `createdBy` (string, required): Who uploaded the version
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The document of the version
  - `fileName` (string, required): File name of the version
  - `fileSize` (integer (int64), required): Size in bytes
  - `id` (string (uuid), required): Version id
  - `mimeType` (string, required): MIME type of the version
  - `s3Path` (string, required): Storage key of the version
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): SHA-256 (hex) of the version
  - `tenantName` (string, required): Tenant name
  - `versionNumber` (integer, required): Version number, from 1
  - `changeSummary` (string): What changed with this version
- `total` (integer, required): Number of versions

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-09-30T08:40:12Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "fileName": "RE-482117.pdf",
      "fileSize": 184320,
      "id": "8a0c2e4a-6b8c-4d0e-8f2a-4b6c8d0e2f4a",
      "mimeType": "application/pdf",
      "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
      "scanStatus": "CLEAN",
      "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
      "tenantName": "DEMO",
      "versionNumber": 1
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/versions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Upload a new version of a document (tenant:dms:write)

`POST /api/dms/v1/documents/{id}/versions`

Module: DMS · operationId: `addDocumentVersion` · Tag: Versions · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores the `file` part as the next version; the previous versions stay. Encrypted documents
only take encrypted versions (`encryption` field) and plain documents only plain ones.
Size limit as for uploads (25 MB by default).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required): The file (exactly one)
- `changeSummary` (string): What changed with this version (max length 1000)
- `encryption` (string): JSON `EncryptionInput`; required for encrypted documents
- `extractText` (boolean): `true` forces, `false` disables text extraction
- `mimeType` (string): Plaintext MIME type of an encrypted version

### Responses

- **201** The document with its new current version and all versions (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **413** Error (`application/json`)
- **415** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
- `createdAt` (string (date-time), required): Upload time
- `currentVersion` (integer, required): Current version number
- `customerNo` (string, required): Customer number of the tenant
- `documentNumber` (string, required): Per-tenant, per-year document number
- `extraction` (Extraction, required): Text extraction state of the current version
  - `attempts` (integer, required): Extraction attempts so far
  - `degraded` (boolean, required): At least one page was extracted in degraded quality
  - `pagesProcessed` (integer, required): Pages extracted so far
  - `pagesTotal` (integer, required): Pages of the file
  - `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)
  - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
  - `error` (string): Error message of a failed extraction
  - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
  - `updatedAt` (string (date-time)): Time of the last state change
- `fileName` (string, required): File name of the current version
- `fileSize` (integer (int64), required): Size of the current version
- `id` (string (uuid), required): Document id
- `isArchived` (boolean, required): Same as `isLocked`
- `isEncrypted` (boolean, required): Content is client-side encrypted
- `isLocked` (boolean, required): WORM lock (same as `isArchived`)
- `isPortalVisible` (boolean, required): Visible in the customer portal
- `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
- `mimeType` (string, required): MIME type of the current version
- `retentionYears` (integer, required): Retention period in years (from the document type)
- `s3Bucket` (string, required): Storage bucket of the current version
- `s3Key` (string, required): Storage key of the current version
- `s3Path` (string, required): Same as `s3Key`
- `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
- `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
- `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
- `tenantName` (string, required): Tenant name
- `title` (string, required): Defaults to the file name
- `updatedAt` (string (date-time), required): Time of the last change
- `uploadedBy` (string, required): Who uploaded the document
- `version` (integer, required): Current version number (same as `currentVersion`)
- `category` (string): Document type code
- `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
- `deletedAt` (string (date-time)): Time of the soft delete
- `encryptionAlgorithm` (string): Only for encrypted documents
- `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
- `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name
- `hashSha256` (string): SHA-256 (hex) of the current version
- `links` (array of DocumentLink): Omitted when the document has none
  - `createdAt` (string (date-time), required): Creation time
  - `createdBy` (string, required): Who created the link
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The linked document
  - `id` (string (uuid), required): Link id
  - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
  - `targetId` (string, required): Id of the linked record
  - `targetModule` (string, required): Module of the linked record
  - `targetType` (string, required): Type of the linked record (see TargetType)
  - `tenantName` (string, required): Tenant name
- `lockRetentionUntil` (string (date-time)): End of the WORM lock
- `metadata` (object): Free metadata (JSON object)
- `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
- `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
- `versions` (array of DocumentVersion): Only in the detail and after a version upload
  - `createdAt` (string (date-time), required): Upload time
  - `createdBy` (string, required): Who uploaded the version
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The document of the version
  - `fileName` (string, required): File name of the version
  - `fileSize` (integer (int64), required): Size in bytes
  - `id` (string (uuid), required): Version id
  - `mimeType` (string, required): MIME type of the version
  - `s3Path` (string, required): Storage key of the version
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): SHA-256 (hex) of the version
  - `tenantName` (string, required): Tenant name
  - `versionNumber` (integer, required): Version number, from 1
  - `changeSummary` (string): What changed with this version

Example 201 answer:

```json
{
  "category": "incoming_document",
  "classificationStatus": "classified",
  "confidentialLevel": "INTERNAL",
  "createdAt": "2026-09-30T08:40:12Z",
  "currentVersion": 1,
  "customerNo": "99999",
  "documentNumber": "DOC-2026-000042",
  "extraction": {
    "attempts": 1,
    "degraded": false,
    "eInvoice": "ZUGFERD",
    "pagesProcessed": 2,
    "pagesTotal": 2,
    "status": "DONE",
    "updatedAt": "2026-09-30T08:41:03Z"
  },
  "fileName": "RE-482117.pdf",
  "fileSize": 184320,
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "folderPath": [
    {
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung"
    },
    {
      "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
      "name": "Eingangsrechnungen 2026"
    }
  ],
  "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "isArchived": true,
  "isEncrypted": false,
  "isLocked": true,
  "isPortalVisible": false,
  "legalHold": false,
  "links": [
    {
      "createdAt": "2026-09-30T08:40:12Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
      "relationType": "ATTACHMENT",
      "targetId": "70001",
      "targetModule": "masterdata",
      "targetType": "SUPPLIER",
      "tenantName": "DEMO"
    }
  ],
  "lockRetentionUntil": "2036-12-31T23:59:59Z",
  "metadata": {
    "invoiceNumber": "RE-482117",
    "supplier": "Nordlicht IT-Distribution GmbH"
  },
  "mimeType": "application/pdf",
  "retentionUntil": "2036-12-31T23:59:59Z",
  "retentionYears": 10,
  "s3Bucket": "99999-demo-prod-mbcom-cloud",
  "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "scanStatus": "CLEAN",
  "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "sizeBytes": 184320,
  "source": "mail",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
  "updatedAt": "2026-09-30T08:41:03Z",
  "uploadedBy": "christina.adler@muster-it.example",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/versions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```

## The file of one version (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/versions/{version}/content`

Module: DMS · operationId: `getDocumentVersionContent` · Tag: Versions · Auth: access token (`Authorization: Bearer <accessToken>`)

Same behaviour, headers and errors as `getDocumentContent` (inline by default, `download=true` for attachment).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `version` | path | integer | yes | Version number |
| `download` | query | boolean |  | `true` serves the file as attachment (default `false`) |

### Responses

- **200** The stored file with its MIME type (`*/*`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/versions/1/content' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Links

## The links of a document (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/links`

Module: DMS · operationId: `listDocumentLinks` · Tag: Links · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Links (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of DocumentLink, required): The links of the document
  - `createdAt` (string (date-time), required): Creation time
  - `createdBy` (string, required): Who created the link
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The linked document
  - `id` (string (uuid), required): Link id
  - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
  - `targetId` (string, required): Id of the linked record
  - `targetModule` (string, required): Module of the linked record
  - `targetType` (string, required): Type of the linked record (see TargetType)
  - `tenantName` (string, required): Tenant name
- `total` (integer, required): Number of links

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-09-30T08:40:12Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
      "relationType": "ATTACHMENT",
      "targetId": "70001",
      "targetModule": "masterdata",
      "targetType": "SUPPLIER",
      "tenantName": "DEMO"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/links' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Link a document to a record (tenant:dms:write)

`POST /api/dms/v1/documents/{id}/links`

Module: DMS · operationId: `addDocumentLink` · Tag: Links · Auth: access token (`Authorization: Bearer <accessToken>`)

Idempotent – an existing identical link is returned again. `STANDALONE` is not a link target (`400`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `targetType` (TargetType, required): Type of the linked record (case-insensitive); `STANDALONE` = no link (one of `CUSTOMER`, `SUPPLIER`, `DISTRIBUTOR`, `ADDRESS`, `ARTICLE`, `TRANSACTION`, `INVOICE`, `CONTRACT`, `EMPLOYEE`, `TRAVEL_REPORT`, `TICKET`, `WORK_ITEM`, `FORGE_ITEM`, `LEAD`, `OPPORTUNITY`, `CAMPAIGN`, `PROJECT`, `ASSET`, `STANDALONE`)
- `relationType` (string): Upper-cased by the server (default `"ATTACHMENT"`)
- `targetId` (string): Id of the record; required unless `STANDALONE` (max length 128)
- `targetModule` (string): Defaults to the module of the target type

Example:

```json
{
  "relationType": "CONTRACT",
  "targetId": "10042",
  "targetType": "CUSTOMER"
}
```

### Responses

- **201** The link (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time), required): Creation time
- `createdBy` (string, required): Who created the link
- `customerNo` (string, required): Customer number of the tenant
- `documentId` (string (uuid), required): The linked document
- `id` (string (uuid), required): Link id
- `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
- `targetId` (string, required): Id of the linked record
- `targetModule` (string, required): Module of the linked record
- `targetType` (string, required): Type of the linked record (see TargetType)
- `tenantName` (string, required): Tenant name

Example 201 answer:

```json
{
  "createdAt": "2026-09-30T08:40:12Z",
  "createdBy": "christina.adler@muster-it.example",
  "customerNo": "99999",
  "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
  "relationType": "ATTACHMENT",
  "targetId": "70001",
  "targetModule": "masterdata",
  "targetType": "SUPPLIER",
  "tenantName": "DEMO"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/links' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"relationType":"CONTRACT","targetId":"10042","targetType":"CUSTOMER"}'
```

## Remove a link (tenant:dms:write)

`DELETE /api/dms/v1/documents/{id}/links/{linkId}`

Module: DMS · operationId: `removeDocumentLink` · Tag: Links · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `linkId` | path | string (uuid) | yes |  |

### Responses

- **204** Removed
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/links/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Text

## Extracted text of a document version (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/text`

Module: DMS · operationId: `getDocumentText` · Tag: Text · Auth: access token (`Authorization: Bearer <accessToken>`)

Returns the text of a finished extraction (`DONE` or `PARTIAL`) as Markdown (default) or
plain text, joined in `text` and per page in `pages`. `structured` holds structured data
when the extractor produced any (e.g. a parsed e-invoice). Audited as `VIEW`.

Without text the answer is `409` while the extraction is still queued or running (`code:
extraction_pending`; retry later) and `422` otherwise (`code` `not_extracted`, `encrypted`
or the extraction's error code such as `no_text` or `pdf_password`); both carry the
extraction `status`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `version` | query | integer |  | Version number; default the current version |
| `format` | query | string |  | (one of `markdown`, `plain`; default `"markdown"`) |
| `pages` | query | string |  | One page `N` or a range `N-M` (1-based) |
| `include` | query | string |  | `text` returns only the joined text (`pages` is empty) (one of `pages`, `text`; default `"pages"`) |

### Responses

- **200** Text (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** No text available (409 extraction still running, 422 no text) (`application/json`)
- **422** No text available (409 extraction still running, 422 no text) (`application/json`)

Fields of the 200 answer:

- `degraded` (boolean, required): At least one page was extracted in degraded quality
- `documentId` (string (uuid), required): Document id
- `pages` (array of TextPage, required): Empty with `include=text`
  - `pageNo` (integer, required): Page number, from 1
  - `source` (string, required): How the page text was obtained (one of `text_layer`, `ocr`, `tika`, `einvoice`)
  - `text` (string, required): Text of the page
- `pagesProcessed` (integer, required): Pages extracted
- `pagesTotal` (integer, required): Pages of the file
- `status` (string, required): Extraction status (PARTIAL: page limit or partial failure) (one of `DONE`, `PARTIAL`)
- `structured` (object, nullable, required): Structured extraction result (e.g. a parsed e-invoice) or null
- `text` (string, required): The selected pages joined by blank lines
- `version` (integer, required): Version the text belongs to
- `model` (string): Model used for OCR, if any

Example 200 answer:

```json
{
  "degraded": false,
  "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "pages": [
    {
      "pageNo": 1,
      "source": "einvoice",
      "text": "# Rechnung RE-482117\n\nNordlicht IT-Distribution GmbH, Hafenstraße 40, 20457 Hamburg"
    },
    {
      "pageNo": 2,
      "source": "einvoice",
      "text": "| Pos. | Artikel | Menge | Einzelpreis |\n|---|---|---|---|\n| 1 | Notebook ProBook 14 G10 | 6 | 829,00 € |\n| 2 | USB-C Dockingstation 100 W | 6 | 139,00 € |\n\nGesamt netto 5.808,00 €, USt. 19 % 1.103,52 €, Gesamt brutto 6.911,52 €"
    }
  ],
  "pagesProcessed": 2,
  "pagesTotal": 2,
  "status": "DONE",
  "structured": {
    "currency": "EUR",
    "grossTotal": 6911.52,
    "invoiceNumber": "RE-482117",
    "issueDate": "2026-09-30",
    "netTotal": 5808,
    "taxTotal": 1103.52
  },
  "text": "# Rechnung RE-482117\n\nNordlicht IT-Distribution GmbH, Hafenstraße 40, 20457 Hamburg\n\n| Pos. | Artikel | Menge | Einzelpreis |\n|---|---|---|---|\n| 1 | Notebook ProBook 14 G10 | 6 | 829,00 € |\n| 2 | USB-C Dockingstation 100 W | 6 | 139,00 € |\n\nGesamt netto 5.808,00 €, USt. 19 % 1.103,52 €, Gesamt brutto 6.911,52 €",
  "version": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/text' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Queue text extraction of a document (tenant:dms:write)

`POST /api/dms/v1/documents/{id}/extract`

Module: DMS · operationId: `requestDocumentExtraction` · Tag: Text · Auth: access token (`Authorization: Bearer <accessToken>`)

Queues the current version for extraction. Without `force` a queued, running or finished
(`DONE`, `PARTIAL`) extraction is left alone and its status returned; `force: true` discards
the stored text and extracts again. The body is optional. Encrypted documents are never
extracted (`400`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `force` (boolean): Discard the stored text and extract again (default `false`)

Example:

```json
{
  "force": true
}
```

### Responses

- **202** Queued (or already queued, running or finished) (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 202 answer:

- `documentId` (string (uuid), required): Document id
- `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)

Example 202 answer:

```json
{
  "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "status": "PENDING"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/extract' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"force":true}'
```

## Queue text extraction of all matching documents again (tenant:dms:admin)

`POST /api/dms/v1/extraction/reprocess`

Module: DMS · operationId: `reprocessExtraction` · Tag: Text · Auth: access token (`Authorization: Bearer <accessToken>`)

Re-queues every matching unencrypted document of the tenant with `force` semantics (stored
text is discarded); queued and running extractions are left alone. All filters are optional
and combined; send `{}` for every document. Writes one audit entry.

### Request body

`application/json` (required)

- `category` (string): Document type code (case-insensitive) (max length 64)
- `createdFrom` (string (date-time)): Created at or after
- `createdTo` (string (date-time)): Created before
- `status` (string): Current extraction status (one of `NONE`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)

Example:

```json
{
  "category": "incoming_document",
  "createdFrom": "2026-01-01T00:00:00Z",
  "status": "FAILED"
}
```

### Responses

- **200** Number of queued documents (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `queued` (integer, required): Documents queued for extraction

Example 200 answer:

```json
{
  "queued": 37
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/extraction/reprocess' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"category":"incoming_document","createdFrom":"2026-01-01T00:00:00Z","status":"FAILED"}'
```

# Folders

## File documents in a folder (tenant:dms:write)

`POST /api/dms/v1/documents/move`

Module: DMS · operationId: `moveDocuments` · Tag: Folders · Auth: access token (`Authorization: Bearer <accessToken>`)

Files up to 500 documents in one folder (`folderId`), or takes them out of every folder
(`folderId: null`). All or nothing: an unknown document answers `404`, an unknown folder
`422`. Every document whose folder changes gets an audit entry (`FOLDER`); WORM-locked
documents and documents under legal hold can be moved, their content and retention stay.

### Request body

`application/json` (required)

- `documentIds` (array of string (uuid), required): Documents to file
- `folderId` (string (uuid), nullable, required): Target folder; `null` takes the documents out of every folder

Example:

```json
{
  "documentIds": [
    "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42"
  ],
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63"
}
```

### Responses

- **200** Moved (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `moved` (integer, required): Documents whose folder changed

Example 200 answer:

```json
{
  "moved": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/move' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"documentIds":["3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42"],"folderId":"3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63"}'
```

## The folder tree with document counts (tenant:dms:read)

`GET /api/dms/v1/folders`

Module: DMS · operationId: `listFolders` · Tag: Folders · Auth: access token (`Authorization: Bearer <accessToken>`)

All folders of the tenant, flat (build the tree with `parentId`), ordered by name, with the documents directly in each folder; plus the documents without a folder and in total.

### Responses

- **200** Folders (`application/json`)

Fields of the 200 answer:

- `items` (array of Folder, required): Every folder of the tenant the caller may see (not paged)
  - `access` (string, required): What the caller may do in the folder (one of `READ`, `WRITE`)
  - `createdAt` (string (date-time), required): Creation time
  - `createdBy` (string, required): Who created the folder
  - `documentCount` (integer, required): Documents directly in the folder (not in subfolders)
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name, unique among its siblings (max length 255)
  - `parentId` (string (uuid), nullable, required): `null` for a top-level folder
  - `restricted` (boolean, required): The folder or a folder above it limits who may use it
  - `updatedAt` (string (date-time), required): Time of the last change
  - `version` (integer, required): Increases with every change; send it with `updateFolder`
- `totalCount` (integer, required): All documents
- `unfiledCount` (integer, required): Documents without a folder

Example 200 answer:

```json
{
  "items": [
    {
      "access": "WRITE",
      "createdAt": "2026-01-02T08:00:00Z",
      "createdBy": "laura.kaestner@muster-it.example",
      "documentCount": 0,
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung",
      "parentId": null,
      "restricted": true,
      "updatedAt": "2026-01-02T08:00:00Z",
      "version": 1
    },
    {
      "access": "WRITE",
      "createdAt": "2026-01-02T08:00:00Z",
      "createdBy": "laura.kaestner@muster-it.example",
      "documentCount": 42,
      "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
      "name": "Eingangsrechnungen 2026",
      "parentId": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "restricted": true,
      "updatedAt": "2026-06-15T10:12:00Z",
      "version": 3
    }
  ],
  "totalCount": 128,
  "unfiledCount": 7
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/folders' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a folder (tenant:dms:write)

`POST /api/dms/v1/folders`

Module: DMS · operationId: `createFolder` · Tag: Folders · Auth: access token (`Authorization: Bearer <accessToken>`)

Without `parentId` the folder is a top-level folder. Names are unique among siblings (ignoring case, `409`), at most 255 characters, without `/`, `\` and control characters.

### Request body

`application/json` (required)

- `name` (string, required): Folder name, unique among its siblings (max length 255)
- `parentId` (string (uuid), nullable): Parent folder; omitted or `null` = top level

Example:

```json
{
  "name": "Rechnungen 2026",
  "parentId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `access` (string, required): What the caller may do in the folder (one of `READ`, `WRITE`)
- `createdAt` (string (date-time), required): Creation time
- `createdBy` (string, required): Who created the folder
- `documentCount` (integer, required): Documents directly in the folder (not in subfolders)
- `id` (string (uuid), required): Folder id
- `name` (string, required): Folder name, unique among its siblings (max length 255)
- `parentId` (string (uuid), nullable, required): `null` for a top-level folder
- `restricted` (boolean, required): The folder or a folder above it limits who may use it
- `updatedAt` (string (date-time), required): Time of the last change
- `version` (integer, required): Increases with every change; send it with `updateFolder`

Example 201 answer:

```json
{
  "access": "WRITE",
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "documentCount": 42,
  "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "name": "Eingangsrechnungen 2026",
  "parentId": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
  "restricted": true,
  "updatedAt": "2026-06-15T10:12:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/folders' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Rechnungen 2026","parentId":"3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63"}'
```

## Delete an empty folder (tenant:dms:write)

`DELETE /api/dms/v1/folders/{id}`

Module: DMS · operationId: `deleteFolder` · Tag: Folders · Auth: access token (`Authorization: Bearer <accessToken>`)

Refused with `409` while the folder has subfolders or documents.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/dms/v1/folders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Rename or move a folder (tenant:dms:write)

`PATCH /api/dms/v1/folders/{id}`

Module: DMS · operationId: `updateFolder` · Tag: Folders · Auth: access token (`Authorization: Bearer <accessToken>`)

Changes `name` and/or `parentId` (`null` = top level; absent = unchanged) at the folder's
`version`. A folder cannot be moved into itself or one of its subfolders (`422`), nor deeper
than 10 levels. `409` when the version is stale or a sibling has the name.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `version` (integer, required): The version the change is based on
- `name` (string): New name; omitted keeps it (max length 255)
- `parentId` (string (uuid), nullable): New parent; `null` = top level; omitted = unchanged

Example:

```json
{
  "name": "Eingangsrechnungen",
  "version": 3
}
```

### Responses

- **200** The folder (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `access` (string, required): What the caller may do in the folder (one of `READ`, `WRITE`)
- `createdAt` (string (date-time), required): Creation time
- `createdBy` (string, required): Who created the folder
- `documentCount` (integer, required): Documents directly in the folder (not in subfolders)
- `id` (string (uuid), required): Folder id
- `name` (string, required): Folder name, unique among its siblings (max length 255)
- `parentId` (string (uuid), nullable, required): `null` for a top-level folder
- `restricted` (boolean, required): The folder or a folder above it limits who may use it
- `updatedAt` (string (date-time), required): Time of the last change
- `version` (integer, required): Increases with every change; send it with `updateFolder`

Example 200 answer:

```json
{
  "access": "WRITE",
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "documentCount": 42,
  "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "name": "Eingangsrechnungen 2026",
  "parentId": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
  "restricted": true,
  "updatedAt": "2026-06-15T10:12:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/dms/v1/folders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Eingangsrechnungen","version":3}'
```

## Who may use a folder (tenant:dms:admin)

`GET /api/dms/v1/folders/{id}/access`

Module: DMS · operationId: `getFolderAccess` · Tag: Folders · Auth: access token (`Authorization: Bearer <accessToken>`)

The folder's own entries and the restricted folders above it (whose entries apply too).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Access (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `entries` (array of FolderAccessEntry, required): Access entries of the folder itself; empty: not restricted by this folder
  - `level` (string, required): READ: read only; WRITE: read and change (one of `READ`, `WRITE`)
  - `principalId` (string, required): E-mail (USER) or key group id (GROUP)
  - `principalType` (string, required): USER: a person by e-mail; GROUP: a DMS key group (one of `USER`, `GROUP`)
  - `name` (string): Name of the key group (responses only)
- `folderId` (string (uuid), required): Folder id
- `inheritedFrom` (array of FolderRef, required): Restricted folders above, top level first
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name

Example 200 answer:

```json
{
  "entries": [
    {
      "level": "WRITE",
      "principalId": "christina.adler@muster-it.example",
      "principalType": "USER"
    },
    {
      "level": "READ",
      "name": "Geschäftsführung",
      "principalId": "5d7f9b1d-3e5a-4c7b-9d1f-7b9d1f3a5c7e",
      "principalType": "GROUP"
    }
  ],
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "inheritedFrom": [
    {
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/folders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/access' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Set who may use a folder (tenant:dms:admin)

`PUT /api/dms/v1/folders/{id}/access`

Module: DMS · operationId: `setFolderAccess` · Tag: Folders · Auth: access token (`Authorization: Bearer <accessToken>`)

Replaces the folder's entries (at most 100). An empty list lifts the folder's own restriction;
restricted folders above still apply. Recorded in the audit trail (`FOLDER_ACCESS`); the
documents below are announced again with `dms.document.filed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `entries` (array of FolderAccessEntry, required): The new entries; replaces all entries of the folder (empty lifts the restriction)
  - `level` (string, required): READ: read only; WRITE: read and change (one of `READ`, `WRITE`)
  - `principalId` (string, required): E-mail (USER) or key group id (GROUP)
  - `principalType` (string, required): USER: a person by e-mail; GROUP: a DMS key group (one of `USER`, `GROUP`)
  - `name` (string): Name of the key group (responses only)

Example:

```json
{
  "entries": [
    {
      "level": "WRITE",
      "principalId": "anna.schmidt@beispiel.de",
      "principalType": "USER"
    }
  ]
}
```

### Responses

- **200** Access (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `entries` (array of FolderAccessEntry, required): Access entries of the folder itself; empty: not restricted by this folder
  - `level` (string, required): READ: read only; WRITE: read and change (one of `READ`, `WRITE`)
  - `principalId` (string, required): E-mail (USER) or key group id (GROUP)
  - `principalType` (string, required): USER: a person by e-mail; GROUP: a DMS key group (one of `USER`, `GROUP`)
  - `name` (string): Name of the key group (responses only)
- `folderId` (string (uuid), required): Folder id
- `inheritedFrom` (array of FolderRef, required): Restricted folders above, top level first
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name

Example 200 answer:

```json
{
  "entries": [
    {
      "level": "WRITE",
      "principalId": "christina.adler@muster-it.example",
      "principalType": "USER"
    },
    {
      "level": "READ",
      "name": "Geschäftsführung",
      "principalId": "5d7f9b1d-3e5a-4c7b-9d1f-7b9d1f3a5c7e",
      "principalType": "GROUP"
    }
  ],
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "inheritedFrom": [
    {
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung"
    }
  ]
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/dms/v1/folders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/access' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"entries":[{"level":"WRITE","principalId":"anna.schmidt@beispiel.de","principalType":"USER"}]}'
```

# Containers

## List containers, newest first (tenant:dms:read)

`GET /api/dms/v1/containers`

Module: DMS · operationId: `listContainers` · Tag: Containers · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | Page size; another value than 1–100 is a `400 invalid` (`field: limit`) (default `50`; max 100) |
| `offset` | query | integer |  | Items to skip; a negative value is a `400 invalid` (default `0`) |

### Responses

- **200** A page of containers with their items (`application/json`)

Fields of the 200 answer:

- `items` (array of DocumentContainer, required): Containers of the page, newest first
  - `containerNumber` (string, required): Per-tenant, per-year container number
  - `containerType` (string, required): Kind of container, an upper-case code
  - `createdAt` (string (date-time), required): Creation time
  - `createdBy` (string, required): Who created the container
  - `customerNo` (string, required): Customer number of the tenant
  - `id` (string (uuid), required): Container id
  - `retentionYears` (integer, required): Retention period in years
  - `sourceChannel` (string, required): Where the container came from, an upper-case code
  - `tenantName` (string, required): Tenant name
  - `title` (string, required): Title
  - `updatedAt` (string (date-time), required): Time of the last change
  - `emlDocumentId` (string (uuid)): The original mail (EML item), if any
  - `items` (array of DocumentContainerItem): The documents of the container (detail only)
    - `containerId` (string (uuid), required): Container id
    - `createdAt` (string (date-time), required): Time the document was added
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): Document id
    - `id` (string (uuid), required): Item id
    - `itemRole` (string, required): `EML`, `ATTACHMENT` or another code
    - `sortOrder` (integer, required): Position in the container
    - `tenantName` (string, required): Tenant name
    - `document` (Document)
  - `metadata` (object): Free metadata (JSON object)
  - `sourceReference` (string): Reference in the source, e.g. a Message-ID
- `total` (integer, required): Number of containers of the tenant

Example 200 answer:

```json
{
  "items": [
    {
      "containerNumber": "CNT-2026-000007",
      "containerType": "EMAIL",
      "createdAt": "2026-09-30T08:40:12Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "emlDocumentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
      "id": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "items": [
        {
          "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
          "createdAt": "2026-09-30T08:40:12Z",
          "customerNo": "99999",
          "documentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
          "id": "4a6c8e0a-2b4c-4d6e-8f0a-0b2c4d6e8f0a",
          "itemRole": "EML",
          "sortOrder": 0,
          "tenantName": "DEMO"
        },
        {
          "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
          "createdAt": "2026-09-30T08:40:12Z",
          "customerNo": "99999",
          "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
          "id": "6c8e0a2c-4d6e-4f8a-9b2c-2d4e6f8a0b2c",
          "itemRole": "ATTACHMENT",
          "sortOrder": 1,
          "tenantName": "DEMO"
        }
      ],
      "metadata": {
        "from": "rechnungen@nordlicht-distribution.example"
      },
      "retentionYears": 10,
      "sourceChannel": "MAIL",
      "sourceReference": "\u003c20260930064512.4711@nordlicht-distribution.example\u003e",
      "tenantName": "DEMO",
      "title": "Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815",
      "updatedAt": "2026-09-30T08:40:12Z"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/containers' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a container (tenant:dms:write)

`POST /api/dms/v1/containers`

Module: DMS · operationId: `createContainer` · Tag: Containers · Auth: access token (`Authorization: Bearer <accessToken>`)

Creates a container and adds the given documents as `ATTACHMENT` items in order; an
`emlDocumentId` is added first as `EML` item. Every referenced document must be an existing
document of the tenant (`400` otherwise).

### Request body

`application/json` (required)

- `containerType` (string, required): Upper-cased by the server (max length 64)
- `title` (string, required): Title (max length 255)
- `documentIds` (array of string (uuid)): Added as `ATTACHMENT` items in this order
- `emlDocumentId` (string (uuid)): The original mail; added as `EML` item
- `metadata` (object): Free metadata (JSON object)
- `retentionYears` (integer): Retention period in years (max 100)
- `sourceChannel` (string): Where the container came from, an upper-case code (default `"MANUAL"`)
- `sourceReference` (string): Reference in the source, e.g. a Message-ID

Example:

```json
{
  "containerType": "EMAIL",
  "documentIds": [
    "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42"
  ],
  "emlDocumentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
  "retentionYears": 10,
  "sourceChannel": "MAIL",
  "sourceReference": "\u003c20260930064512.4711@nordlicht-distribution.example\u003e",
  "title": "Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815"
}
```

### Responses

- **201** The container with its items (`application/json`)
- **400** Error (`application/json`)

Fields of the 201 answer:

- `containerNumber` (string, required): Per-tenant, per-year container number
- `containerType` (string, required): Kind of container, an upper-case code
- `createdAt` (string (date-time), required): Creation time
- `createdBy` (string, required): Who created the container
- `customerNo` (string, required): Customer number of the tenant
- `id` (string (uuid), required): Container id
- `retentionYears` (integer, required): Retention period in years
- `sourceChannel` (string, required): Where the container came from, an upper-case code
- `tenantName` (string, required): Tenant name
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Time of the last change
- `emlDocumentId` (string (uuid)): The original mail (EML item), if any
- `items` (array of DocumentContainerItem): The documents of the container (detail only)
  - `containerId` (string (uuid), required): Container id
  - `createdAt` (string (date-time), required): Time the document was added
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): Document id
  - `id` (string (uuid), required): Item id
  - `itemRole` (string, required): `EML`, `ATTACHMENT` or another code
  - `sortOrder` (integer, required): Position in the container
  - `tenantName` (string, required): Tenant name
  - `document` (Document)
    - `confidentialLevel` (ConfidentialLevel, required)
    - `createdAt` (string (date-time), required): Upload time
    - `currentVersion` (integer, required): Current version number
    - `customerNo` (string, required): Customer number of the tenant
    - `documentNumber` (string, required): Per-tenant, per-year document number
    - `extraction` (Extraction, required)
    - `fileName` (string, required): File name of the current version
    - `fileSize` (integer (int64), required): Size of the current version
    - `id` (string (uuid), required): Document id
    - `isArchived` (boolean, required): Same as `isLocked`
    - `isEncrypted` (boolean, required): Content is client-side encrypted
    - `isLocked` (boolean, required): WORM lock (same as `isArchived`)
    - `isPortalVisible` (boolean, required): Visible in the customer portal
    - `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
    - `mimeType` (string, required): MIME type of the current version
    - `retentionYears` (integer, required): Retention period in years (from the document type)
    - `s3Bucket` (string, required): Storage bucket of the current version
    - `s3Key` (string, required): Storage key of the current version
    - `s3Path` (string, required): Same as `s3Key`
    - `scanStatus` (ScanStatus, required)
    - `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
    - `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
    - `tenantName` (string, required): Tenant name
    - `title` (string, required): Defaults to the file name
    - `updatedAt` (string (date-time), required): Time of the last change
    - `uploadedBy` (string, required): Who uploaded the document
    - `version` (integer, required): Current version number (same as `currentVersion`)
    - `category` (string): Document type code
    - `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
    - `deletedAt` (string (date-time)): Time of the soft delete
    - `encryptionAlgorithm` (string): Only for encrypted documents
    - `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
    - `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
    - `hashSha256` (string): SHA-256 (hex) of the current version
    - `links` (array of DocumentLink): Omitted when the document has none
    - `lockRetentionUntil` (string (date-time)): End of the WORM lock
    - `metadata` (object): Free metadata (JSON object)
    - `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
    - `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
    - `versions` (array of DocumentVersion): Only in the detail and after a version upload
- `metadata` (object): Free metadata (JSON object)
- `sourceReference` (string): Reference in the source, e.g. a Message-ID

Example 201 answer:

```json
{
  "containerNumber": "CNT-2026-000007",
  "containerType": "EMAIL",
  "createdAt": "2026-09-30T08:40:12Z",
  "createdBy": "christina.adler@muster-it.example",
  "customerNo": "99999",
  "emlDocumentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
  "id": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
  "items": [
    {
      "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "documentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
      "id": "4a6c8e0a-2b4c-4d6e-8f0a-0b2c4d6e8f0a",
      "itemRole": "EML",
      "sortOrder": 0,
      "tenantName": "DEMO"
    },
    {
      "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6c8e0a2c-4d6e-4f8a-9b2c-2d4e6f8a0b2c",
      "itemRole": "ATTACHMENT",
      "sortOrder": 1,
      "tenantName": "DEMO"
    }
  ],
  "metadata": {
    "from": "rechnungen@nordlicht-distribution.example"
  },
  "retentionYears": 10,
  "sourceChannel": "MAIL",
  "sourceReference": "\u003c20260930064512.4711@nordlicht-distribution.example\u003e",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815",
  "updatedAt": "2026-09-30T08:40:12Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/containers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"containerType":"EMAIL","documentIds":["3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42"],"emlDocumentId":"2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e","retentionYears":10,"sourceChannel":"MAIL","sourceReference":"\u003c20260930064512.4711@nordlicht-distribution.example\u003e","title":"Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815"}'
```

## A container with its items (tenant:dms:read)

`GET /api/dms/v1/containers/{id}`

Module: DMS · operationId: `getContainer` · Tag: Containers · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Container (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `containerNumber` (string, required): Per-tenant, per-year container number
- `containerType` (string, required): Kind of container, an upper-case code
- `createdAt` (string (date-time), required): Creation time
- `createdBy` (string, required): Who created the container
- `customerNo` (string, required): Customer number of the tenant
- `id` (string (uuid), required): Container id
- `retentionYears` (integer, required): Retention period in years
- `sourceChannel` (string, required): Where the container came from, an upper-case code
- `tenantName` (string, required): Tenant name
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Time of the last change
- `emlDocumentId` (string (uuid)): The original mail (EML item), if any
- `items` (array of DocumentContainerItem): The documents of the container (detail only)
  - `containerId` (string (uuid), required): Container id
  - `createdAt` (string (date-time), required): Time the document was added
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): Document id
  - `id` (string (uuid), required): Item id
  - `itemRole` (string, required): `EML`, `ATTACHMENT` or another code
  - `sortOrder` (integer, required): Position in the container
  - `tenantName` (string, required): Tenant name
  - `document` (Document)
    - `confidentialLevel` (ConfidentialLevel, required)
    - `createdAt` (string (date-time), required): Upload time
    - `currentVersion` (integer, required): Current version number
    - `customerNo` (string, required): Customer number of the tenant
    - `documentNumber` (string, required): Per-tenant, per-year document number
    - `extraction` (Extraction, required)
    - `fileName` (string, required): File name of the current version
    - `fileSize` (integer (int64), required): Size of the current version
    - `id` (string (uuid), required): Document id
    - `isArchived` (boolean, required): Same as `isLocked`
    - `isEncrypted` (boolean, required): Content is client-side encrypted
    - `isLocked` (boolean, required): WORM lock (same as `isArchived`)
    - `isPortalVisible` (boolean, required): Visible in the customer portal
    - `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
    - `mimeType` (string, required): MIME type of the current version
    - `retentionYears` (integer, required): Retention period in years (from the document type)
    - `s3Bucket` (string, required): Storage bucket of the current version
    - `s3Key` (string, required): Storage key of the current version
    - `s3Path` (string, required): Same as `s3Key`
    - `scanStatus` (ScanStatus, required)
    - `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
    - `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
    - `tenantName` (string, required): Tenant name
    - `title` (string, required): Defaults to the file name
    - `updatedAt` (string (date-time), required): Time of the last change
    - `uploadedBy` (string, required): Who uploaded the document
    - `version` (integer, required): Current version number (same as `currentVersion`)
    - `category` (string): Document type code
    - `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
    - `deletedAt` (string (date-time)): Time of the soft delete
    - `encryptionAlgorithm` (string): Only for encrypted documents
    - `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
    - `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
    - `hashSha256` (string): SHA-256 (hex) of the current version
    - `links` (array of DocumentLink): Omitted when the document has none
    - `lockRetentionUntil` (string (date-time)): End of the WORM lock
    - `metadata` (object): Free metadata (JSON object)
    - `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
    - `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
    - `versions` (array of DocumentVersion): Only in the detail and after a version upload
- `metadata` (object): Free metadata (JSON object)
- `sourceReference` (string): Reference in the source, e.g. a Message-ID

Example 200 answer:

```json
{
  "containerNumber": "CNT-2026-000007",
  "containerType": "EMAIL",
  "createdAt": "2026-09-30T08:40:12Z",
  "createdBy": "christina.adler@muster-it.example",
  "customerNo": "99999",
  "emlDocumentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
  "id": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
  "items": [
    {
      "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "documentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
      "id": "4a6c8e0a-2b4c-4d6e-8f0a-0b2c4d6e8f0a",
      "itemRole": "EML",
      "sortOrder": 0,
      "tenantName": "DEMO"
    },
    {
      "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6c8e0a2c-4d6e-4f8a-9b2c-2d4e6f8a0b2c",
      "itemRole": "ATTACHMENT",
      "sortOrder": 1,
      "tenantName": "DEMO"
    }
  ],
  "metadata": {
    "from": "rechnungen@nordlicht-distribution.example"
  },
  "retentionYears": 10,
  "sourceChannel": "MAIL",
  "sourceReference": "\u003c20260930064512.4711@nordlicht-distribution.example\u003e",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815",
  "updatedAt": "2026-09-30T08:40:12Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/containers/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Add a document to a container (tenant:dms:write)

`POST /api/dms/v1/containers/{id}/items`

Module: DMS · operationId: `addContainerItem` · Tag: Containers · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `documentId` (string (uuid), required): Document to add
- `itemRole` (string): Role of the document in the container (default `"ATTACHMENT"`)
- `sortOrder` (integer): Position in the container

Example:

```json
{
  "documentId": "7e9a1c3e-5f7a-4b9c-8d1e-3f5a7b9c1d3e",
  "itemRole": "ATTACHMENT",
  "sortOrder": 2
}
```

### Responses

- **200** The container with its items (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `containerNumber` (string, required): Per-tenant, per-year container number
- `containerType` (string, required): Kind of container, an upper-case code
- `createdAt` (string (date-time), required): Creation time
- `createdBy` (string, required): Who created the container
- `customerNo` (string, required): Customer number of the tenant
- `id` (string (uuid), required): Container id
- `retentionYears` (integer, required): Retention period in years
- `sourceChannel` (string, required): Where the container came from, an upper-case code
- `tenantName` (string, required): Tenant name
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Time of the last change
- `emlDocumentId` (string (uuid)): The original mail (EML item), if any
- `items` (array of DocumentContainerItem): The documents of the container (detail only)
  - `containerId` (string (uuid), required): Container id
  - `createdAt` (string (date-time), required): Time the document was added
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): Document id
  - `id` (string (uuid), required): Item id
  - `itemRole` (string, required): `EML`, `ATTACHMENT` or another code
  - `sortOrder` (integer, required): Position in the container
  - `tenantName` (string, required): Tenant name
  - `document` (Document)
    - `confidentialLevel` (ConfidentialLevel, required)
    - `createdAt` (string (date-time), required): Upload time
    - `currentVersion` (integer, required): Current version number
    - `customerNo` (string, required): Customer number of the tenant
    - `documentNumber` (string, required): Per-tenant, per-year document number
    - `extraction` (Extraction, required)
    - `fileName` (string, required): File name of the current version
    - `fileSize` (integer (int64), required): Size of the current version
    - `id` (string (uuid), required): Document id
    - `isArchived` (boolean, required): Same as `isLocked`
    - `isEncrypted` (boolean, required): Content is client-side encrypted
    - `isLocked` (boolean, required): WORM lock (same as `isArchived`)
    - `isPortalVisible` (boolean, required): Visible in the customer portal
    - `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
    - `mimeType` (string, required): MIME type of the current version
    - `retentionYears` (integer, required): Retention period in years (from the document type)
    - `s3Bucket` (string, required): Storage bucket of the current version
    - `s3Key` (string, required): Storage key of the current version
    - `s3Path` (string, required): Same as `s3Key`
    - `scanStatus` (ScanStatus, required)
    - `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
    - `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
    - `tenantName` (string, required): Tenant name
    - `title` (string, required): Defaults to the file name
    - `updatedAt` (string (date-time), required): Time of the last change
    - `uploadedBy` (string, required): Who uploaded the document
    - `version` (integer, required): Current version number (same as `currentVersion`)
    - `category` (string): Document type code
    - `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
    - `deletedAt` (string (date-time)): Time of the soft delete
    - `encryptionAlgorithm` (string): Only for encrypted documents
    - `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
    - `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
    - `hashSha256` (string): SHA-256 (hex) of the current version
    - `links` (array of DocumentLink): Omitted when the document has none
    - `lockRetentionUntil` (string (date-time)): End of the WORM lock
    - `metadata` (object): Free metadata (JSON object)
    - `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
    - `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
    - `versions` (array of DocumentVersion): Only in the detail and after a version upload
- `metadata` (object): Free metadata (JSON object)
- `sourceReference` (string): Reference in the source, e.g. a Message-ID

Example 200 answer:

```json
{
  "containerNumber": "CNT-2026-000007",
  "containerType": "EMAIL",
  "createdAt": "2026-09-30T08:40:12Z",
  "createdBy": "christina.adler@muster-it.example",
  "customerNo": "99999",
  "emlDocumentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
  "id": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
  "items": [
    {
      "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "documentId": "2e4a6c8e-0f2a-4b4c-8d6e-8f0a2b4c6d8e",
      "id": "4a6c8e0a-2b4c-4d6e-8f0a-0b2c4d6e8f0a",
      "itemRole": "EML",
      "sortOrder": 0,
      "tenantName": "DEMO"
    },
    {
      "containerId": "0c2e4a6c-8d0e-4f2a-9b4c-6d8e0f2a4b6c",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6c8e0a2c-4d6e-4f8a-9b2c-2d4e6f8a0b2c",
      "itemRole": "ATTACHMENT",
      "sortOrder": 1,
      "tenantName": "DEMO"
    }
  ],
  "metadata": {
    "from": "rechnungen@nordlicht-distribution.example"
  },
  "retentionYears": 10,
  "sourceChannel": "MAIL",
  "sourceReference": "\u003c20260930064512.4711@nordlicht-distribution.example\u003e",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 zu Ihrer Bestellung BE-2026-0815",
  "updatedAt": "2026-09-30T08:40:12Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/containers/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"documentId":"7e9a1c3e-5f7a-4b9c-8d1e-3f5a7b9c1d3e","itemRole":"ATTACHMENT","sortOrder":2}'
```

## The original mail (EML) of a container (tenant:dms:read)

`GET /api/dms/v1/containers/{id}/eml`

Module: DMS · operationId: `getContainerEml` · Tag: Containers · Auth: access token (`Authorization: Bearer <accessToken>`)

Streams the container's EML document like `getDocumentContent` (inline by default, `download=true` for attachment); `404` when the container has none.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `download` | query | boolean |  | `true` serves the file as attachment (default `false`) |

### Responses

- **200** The stored file with its MIME type (`*/*`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/containers/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/eml' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Compliance

## Set or extend the WORM lock of a document (tenant:dms:write)

`POST /api/dms/v1/documents/{id}/lock`

Module: DMS · operationId: `lockDocument` · Tag: Compliance · Auth: access token (`Authorization: Bearer <accessToken>`)

Locks the document until `retentionUntil` (a date means the end of that day, UTC). An
existing lock and the retention period are only ever extended: an earlier date keeps the
later one. The date must be in the future.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `retentionUntil` (string, required): A date (`YYYY-MM-DD`, end of that day UTC) or an RFC 3339 timestamp; must be in the future

Example:

```json
{
  "retentionUntil": "2036-12-31"
}
```

### Responses

- **200** The locked document (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
- `createdAt` (string (date-time), required): Upload time
- `currentVersion` (integer, required): Current version number
- `customerNo` (string, required): Customer number of the tenant
- `documentNumber` (string, required): Per-tenant, per-year document number
- `extraction` (Extraction, required): Text extraction state of the current version
  - `attempts` (integer, required): Extraction attempts so far
  - `degraded` (boolean, required): At least one page was extracted in degraded quality
  - `pagesProcessed` (integer, required): Pages extracted so far
  - `pagesTotal` (integer, required): Pages of the file
  - `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)
  - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
  - `error` (string): Error message of a failed extraction
  - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
  - `updatedAt` (string (date-time)): Time of the last state change
- `fileName` (string, required): File name of the current version
- `fileSize` (integer (int64), required): Size of the current version
- `id` (string (uuid), required): Document id
- `isArchived` (boolean, required): Same as `isLocked`
- `isEncrypted` (boolean, required): Content is client-side encrypted
- `isLocked` (boolean, required): WORM lock (same as `isArchived`)
- `isPortalVisible` (boolean, required): Visible in the customer portal
- `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
- `mimeType` (string, required): MIME type of the current version
- `retentionYears` (integer, required): Retention period in years (from the document type)
- `s3Bucket` (string, required): Storage bucket of the current version
- `s3Key` (string, required): Storage key of the current version
- `s3Path` (string, required): Same as `s3Key`
- `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
- `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
- `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
- `tenantName` (string, required): Tenant name
- `title` (string, required): Defaults to the file name
- `updatedAt` (string (date-time), required): Time of the last change
- `uploadedBy` (string, required): Who uploaded the document
- `version` (integer, required): Current version number (same as `currentVersion`)
- `category` (string): Document type code
- `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
- `deletedAt` (string (date-time)): Time of the soft delete
- `encryptionAlgorithm` (string): Only for encrypted documents
- `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
- `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name
- `hashSha256` (string): SHA-256 (hex) of the current version
- `links` (array of DocumentLink): Omitted when the document has none
  - `createdAt` (string (date-time), required): Creation time
  - `createdBy` (string, required): Who created the link
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The linked document
  - `id` (string (uuid), required): Link id
  - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
  - `targetId` (string, required): Id of the linked record
  - `targetModule` (string, required): Module of the linked record
  - `targetType` (string, required): Type of the linked record (see TargetType)
  - `tenantName` (string, required): Tenant name
- `lockRetentionUntil` (string (date-time)): End of the WORM lock
- `metadata` (object): Free metadata (JSON object)
- `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
- `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
- `versions` (array of DocumentVersion): Only in the detail and after a version upload
  - `createdAt` (string (date-time), required): Upload time
  - `createdBy` (string, required): Who uploaded the version
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The document of the version
  - `fileName` (string, required): File name of the version
  - `fileSize` (integer (int64), required): Size in bytes
  - `id` (string (uuid), required): Version id
  - `mimeType` (string, required): MIME type of the version
  - `s3Path` (string, required): Storage key of the version
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): SHA-256 (hex) of the version
  - `tenantName` (string, required): Tenant name
  - `versionNumber` (integer, required): Version number, from 1
  - `changeSummary` (string): What changed with this version

Example 200 answer:

```json
{
  "category": "incoming_document",
  "classificationStatus": "classified",
  "confidentialLevel": "INTERNAL",
  "createdAt": "2026-09-30T08:40:12Z",
  "currentVersion": 1,
  "customerNo": "99999",
  "documentNumber": "DOC-2026-000042",
  "extraction": {
    "attempts": 1,
    "degraded": false,
    "eInvoice": "ZUGFERD",
    "pagesProcessed": 2,
    "pagesTotal": 2,
    "status": "DONE",
    "updatedAt": "2026-09-30T08:41:03Z"
  },
  "fileName": "RE-482117.pdf",
  "fileSize": 184320,
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "folderPath": [
    {
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung"
    },
    {
      "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
      "name": "Eingangsrechnungen 2026"
    }
  ],
  "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "isArchived": true,
  "isEncrypted": false,
  "isLocked": true,
  "isPortalVisible": false,
  "legalHold": false,
  "links": [
    {
      "createdAt": "2026-09-30T08:40:12Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
      "relationType": "ATTACHMENT",
      "targetId": "70001",
      "targetModule": "masterdata",
      "targetType": "SUPPLIER",
      "tenantName": "DEMO"
    }
  ],
  "lockRetentionUntil": "2036-12-31T23:59:59Z",
  "metadata": {
    "invoiceNumber": "RE-482117",
    "supplier": "Nordlicht IT-Distribution GmbH"
  },
  "mimeType": "application/pdf",
  "retentionUntil": "2036-12-31T23:59:59Z",
  "retentionYears": 10,
  "s3Bucket": "99999-demo-prod-mbcom-cloud",
  "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "scanStatus": "CLEAN",
  "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "sizeBytes": 184320,
  "source": "mail",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
  "updatedAt": "2026-09-30T08:41:03Z",
  "uploadedBy": "christina.adler@muster-it.example",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/lock' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"retentionUntil":"2036-12-31"}'
```

## The audit trail of a document (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/audit`

Module: DMS · operationId: `getDocumentAudit` · Tag: Compliance · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Audit entries, oldest first (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of AuditEntry, required): The audit entries of the document
  - `action` (string, required): What happened (one of `CREATE`, `VIEW`, `DOWNLOAD`, `LINK`, `UNLINK`, `VERSION`, `LOCK`, `LEGAL_HOLD`, `LEGAL_HOLD_RELEASED`, `DELETE`, `PURGE`, `EXPORT`, `VERIFY`, `KEY`, `EXTRACT`, `SCAN_INFECTED`, `FOLDER`, `FOLDER_CREATE`, `FOLDER_UPDATE`, `FOLDER_DELETE`, `FOLDER_ACCESS`)
  - `actor` (string, required): Who did it
  - `clientIp` (string, required): IP address of the caller
  - `createdAt` (string (date-time), required): Time of the entry
  - `customerNo` (string, required): Customer number of the tenant
  - `details` (string, required): JSON text with action details
  - `entryHash` (string, required): SHA-256 over prevHash and the fields of this entry (hash chain)
  - `id` (integer (int64), required): Entry id
  - `prevHash` (string, required): entryHash of the previous entry of the tenant
  - `tenantName` (string, required): Tenant name
  - `documentId` (string (uuid)): The document the entry is about, if any
- `total` (integer, required): Number of entries

Example 200 answer:

```json
{
  "items": [
    {
      "action": "CREATE",
      "actor": "christina.adler@muster-it.example",
      "clientIp": "203.0.113.17",
      "createdAt": "2026-09-30T08:40:12Z",
      "customerNo": "99999",
      "details": "{\"fileName\":\"RE-482117.pdf\",\"version\":1}",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "entryHash": "3c7a1e9f5b2d8c4e0a6f1b7d3e9c5a2f8b4d0e6c1a7f3b9d5e2c8a4f0b6d1e9c",
      "id": 18001,
      "prevHash": "0a4e8c2f6b1d9e3a7c5f0b8d4e2a6c1f9d7b3e5a0c8f2d6b4e1a9c7f3d5b0e8a",
      "tenantName": "DEMO"
    },
    {
      "action": "DOWNLOAD",
      "actor": "laura.kaestner@muster-it.example",
      "clientIp": "203.0.113.24",
      "createdAt": "2026-10-02T13:15:40Z",
      "customerNo": "99999",
      "details": "{\"version\":1}",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "entryHash": "9e5b1d7a3f0c6e2b8d4a1f7c3e9b5d0a6c2f8e4b1d7a3c9f5e0b6d2a8c4f1e7b",
      "id": 18044,
      "prevHash": "3c7a1e9f5b2d8c4e0a6f1b7d3e9c5a2f8b4d0e6c1a7f3b9d5e2c8a4f0b6d1e9c",
      "tenantName": "DEMO"
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/audit' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Check the integrity of a document (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/verify`

Module: DMS · operationId: `verifyDocument` · Tag: Compliance · Auth: access token (`Authorization: Bearer <accessToken>`)

Recomputes the SHA-256 of every stored version, compares it with the recorded hash and verifies the tenant's audit chain.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Integrity report (`application/json`)
- **404** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `auditChain` (ChainVerification, required)
  - `entries` (integer, required): Entries checked
  - `valid` (boolean, required): Every entry hash matches
  - `brokenAtId` (integer (int64)): First entry whose hash does not match
  - `headHash` (string): Hash of the latest entry
- `documentId` (string (uuid), required): Document id
- `valid` (boolean, required): Every version and the audit chain are intact
- `verifiedAt` (string (date-time), required): Time of the check
- `versions` (array of object, required): Result per version
  - `expectedSha256` (string, required): Recorded SHA-256
  - `valid` (boolean, required): Both hashes match
  - `versionNumber` (integer, required): Version number
  - `actualSha256` (string): SHA-256 of the stored file
  - `error` (string): Why the file could not be checked

Example 200 answer:

```json
{
  "auditChain": {
    "entries": 18342,
    "headHash": "7b1e9c3a5f2d8e4b0a6c1f7d3e9b5a2c8f4d0e6a1b7c3f9d5e2a8b4c0f6d1e7a",
    "valid": true
  },
  "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "valid": true,
  "verifiedAt": "2026-11-18T09:30:00Z",
  "versions": [
    {
      "actualSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
      "expectedSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
      "valid": true,
      "versionNumber": 1
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/verify' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Place or release a legal hold (tenant:dms:admin)

`POST /api/dms/v1/documents/{id}/legal-hold`

Module: DMS · operationId: `setDocumentLegalHold` · Tag: Compliance · Auth: access token (`Authorization: Bearer <accessToken>`)

A document under legal hold can be neither deleted nor purged. Placing a hold (`active: true`) needs a `reason`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `active` (boolean): `true` places, `false` releases the hold
- `reason` (string): Required when `active` is true

Example:

```json
{
  "active": true,
  "reason": "Betriebsprüfung 2026"
}
```

### Responses

- **200** The document (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
- `createdAt` (string (date-time), required): Upload time
- `currentVersion` (integer, required): Current version number
- `customerNo` (string, required): Customer number of the tenant
- `documentNumber` (string, required): Per-tenant, per-year document number
- `extraction` (Extraction, required): Text extraction state of the current version
  - `attempts` (integer, required): Extraction attempts so far
  - `degraded` (boolean, required): At least one page was extracted in degraded quality
  - `pagesProcessed` (integer, required): Pages extracted so far
  - `pagesTotal` (integer, required): Pages of the file
  - `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)
  - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
  - `error` (string): Error message of a failed extraction
  - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
  - `updatedAt` (string (date-time)): Time of the last state change
- `fileName` (string, required): File name of the current version
- `fileSize` (integer (int64), required): Size of the current version
- `id` (string (uuid), required): Document id
- `isArchived` (boolean, required): Same as `isLocked`
- `isEncrypted` (boolean, required): Content is client-side encrypted
- `isLocked` (boolean, required): WORM lock (same as `isArchived`)
- `isPortalVisible` (boolean, required): Visible in the customer portal
- `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
- `mimeType` (string, required): MIME type of the current version
- `retentionYears` (integer, required): Retention period in years (from the document type)
- `s3Bucket` (string, required): Storage bucket of the current version
- `s3Key` (string, required): Storage key of the current version
- `s3Path` (string, required): Same as `s3Key`
- `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
- `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
- `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
- `tenantName` (string, required): Tenant name
- `title` (string, required): Defaults to the file name
- `updatedAt` (string (date-time), required): Time of the last change
- `uploadedBy` (string, required): Who uploaded the document
- `version` (integer, required): Current version number (same as `currentVersion`)
- `category` (string): Document type code
- `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
- `deletedAt` (string (date-time)): Time of the soft delete
- `encryptionAlgorithm` (string): Only for encrypted documents
- `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
- `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name
- `hashSha256` (string): SHA-256 (hex) of the current version
- `links` (array of DocumentLink): Omitted when the document has none
  - `createdAt` (string (date-time), required): Creation time
  - `createdBy` (string, required): Who created the link
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The linked document
  - `id` (string (uuid), required): Link id
  - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
  - `targetId` (string, required): Id of the linked record
  - `targetModule` (string, required): Module of the linked record
  - `targetType` (string, required): Type of the linked record (see TargetType)
  - `tenantName` (string, required): Tenant name
- `lockRetentionUntil` (string (date-time)): End of the WORM lock
- `metadata` (object): Free metadata (JSON object)
- `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
- `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
- `versions` (array of DocumentVersion): Only in the detail and after a version upload
  - `createdAt` (string (date-time), required): Upload time
  - `createdBy` (string, required): Who uploaded the version
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The document of the version
  - `fileName` (string, required): File name of the version
  - `fileSize` (integer (int64), required): Size in bytes
  - `id` (string (uuid), required): Version id
  - `mimeType` (string, required): MIME type of the version
  - `s3Path` (string, required): Storage key of the version
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): SHA-256 (hex) of the version
  - `tenantName` (string, required): Tenant name
  - `versionNumber` (integer, required): Version number, from 1
  - `changeSummary` (string): What changed with this version

Example 200 answer:

```json
{
  "category": "incoming_document",
  "classificationStatus": "classified",
  "confidentialLevel": "INTERNAL",
  "createdAt": "2026-09-30T08:40:12Z",
  "currentVersion": 1,
  "customerNo": "99999",
  "documentNumber": "DOC-2026-000042",
  "extraction": {
    "attempts": 1,
    "degraded": false,
    "eInvoice": "ZUGFERD",
    "pagesProcessed": 2,
    "pagesTotal": 2,
    "status": "DONE",
    "updatedAt": "2026-09-30T08:41:03Z"
  },
  "fileName": "RE-482117.pdf",
  "fileSize": 184320,
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "folderPath": [
    {
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung"
    },
    {
      "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
      "name": "Eingangsrechnungen 2026"
    }
  ],
  "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "isArchived": true,
  "isEncrypted": false,
  "isLocked": true,
  "isPortalVisible": false,
  "legalHold": false,
  "links": [
    {
      "createdAt": "2026-09-30T08:40:12Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
      "relationType": "ATTACHMENT",
      "targetId": "70001",
      "targetModule": "masterdata",
      "targetType": "SUPPLIER",
      "tenantName": "DEMO"
    }
  ],
  "lockRetentionUntil": "2036-12-31T23:59:59Z",
  "metadata": {
    "invoiceNumber": "RE-482117",
    "supplier": "Nordlicht IT-Distribution GmbH"
  },
  "mimeType": "application/pdf",
  "retentionUntil": "2036-12-31T23:59:59Z",
  "retentionYears": 10,
  "s3Bucket": "99999-demo-prod-mbcom-cloud",
  "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "scanStatus": "CLEAN",
  "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "sizeBytes": 184320,
  "source": "mail",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
  "updatedAt": "2026-09-30T08:41:03Z",
  "uploadedBy": "christina.adler@muster-it.example",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/legal-hold' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"reason":"Betriebsprüfung 2026"}'
```

## Verify the tenant's audit chain (tenant:dms:admin)

`GET /api/dms/v1/audit/verify`

Module: DMS · operationId: `verifyAuditChain` · Tag: Compliance · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Result (`application/json`)

Fields of the 200 answer:

- `entries` (integer, required): Entries checked
- `valid` (boolean, required): Every entry hash matches
- `brokenAtId` (integer (int64)): First entry whose hash does not match
- `headHash` (string): Hash of the latest entry

Example 200 answer:

```json
{
  "entries": 18342,
  "headHash": "7b1e9c3a5f2d8e4b0a6c1f7d3e9b5a2c8f4d0e6a1b7c3f9d5e2a8b4c0f6d1e7a",
  "valid": true
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/audit/verify' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Exports

## List auditor exports (tenant:dms:admin)

`GET /api/dms/v1/exports`

Module: DMS · operationId: `listExports` · Tag: Exports · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Exports (`application/json`)

Fields of the 200 answer:

- `items` (array of Export, required): The auditor exports
  - `categories` (array of string, required): Document types included; empty: all
  - `createdAt` (string (date-time), required): Start time
  - `createdBy` (string, required): Who started the export
  - `customerNo` (string, required): Customer number of the tenant
  - `documentCount` (integer, required): Documents in the export
  - `from` (string (date-time), required): Documents created from
  - `id` (string (uuid), required): Export id
  - `sizeBytes` (integer (int64), required): Size of the ZIP in bytes
  - `status` (string, required): PENDING while it is built (one of `PENDING`, `DONE`, `FAILED`)
  - `tenantName` (string, required): Tenant name
  - `to` (string (date-time), required): Documents created until
  - `completedAt` (string (date-time)): Time the export finished
  - `error` (string): Why the export failed
  - `sha256` (string): SHA-256 of the ZIP once done
- `total` (integer, required): Number of exports

Example 200 answer:

```json
{
  "items": [
    {
      "categories": [
        "incoming_document",
        "outgoing_invoice"
      ],
      "completedAt": "2026-02-03T09:06:41Z",
      "createdAt": "2026-02-03T09:00:00Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "documentCount": 1284,
      "from": "2025-01-01T00:00:00Z",
      "id": "9b1d3f5b-7c9e-4a1b-8d3f-5b7c9e1a3b5d",
      "sha256": "c4a9e1f7b3d5028e6a4c9f1b7d3e5a2c8f0b6d4e2a9c7f5b1d3e8a6c0f4b2d9e",
      "sizeBytes": 412318720,
      "status": "DONE",
      "tenantName": "DEMO",
      "to": "2025-12-31T23:59:59Z"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/exports' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Start an auditor export (tenant:dms:admin)

`POST /api/dms/v1/exports`

Module: DMS · operationId: `createExport` · Tag: Exports · Auth: access token (`Authorization: Bearer <accessToken>`)

Selects the documents created in `from`…`to` (dates are whole days, UTC; at most 11 years),
optionally only of the given document types, and builds a ZIP with `index.xml`, `index.csv`,
the files and their hashes in the background. Files the malware scan found infected are
listed in the index but not included. Poll `getExport` until `status` is `DONE`
(or `FAILED`), then download it.

### Request body

`application/json` (required)

- `from` (string, required): Date (`YYYY-MM-DD`) or RFC 3339 timestamp
- `to` (string, required): Date (`YYYY-MM-DD`, inclusive) or RFC 3339 timestamp
- `categories` (array of string): Only these document types; empty = all

Example:

```json
{
  "categories": [
    "incoming_document",
    "contract"
  ],
  "from": "2025-01-01",
  "to": "2025-12-31"
}
```

### Responses

- **202** Started (status PENDING) (`application/json`)
- **400** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 202 answer:

- `categories` (array of string, required): Document types included; empty: all
- `createdAt` (string (date-time), required): Start time
- `createdBy` (string, required): Who started the export
- `customerNo` (string, required): Customer number of the tenant
- `documentCount` (integer, required): Documents in the export
- `from` (string (date-time), required): Documents created from
- `id` (string (uuid), required): Export id
- `sizeBytes` (integer (int64), required): Size of the ZIP in bytes
- `status` (string, required): PENDING while it is built (one of `PENDING`, `DONE`, `FAILED`)
- `tenantName` (string, required): Tenant name
- `to` (string (date-time), required): Documents created until
- `completedAt` (string (date-time)): Time the export finished
- `error` (string): Why the export failed
- `sha256` (string): SHA-256 of the ZIP once done

Example 202 answer:

```json
{
  "categories": [
    "incoming_document",
    "outgoing_invoice"
  ],
  "completedAt": "2026-02-03T09:06:41Z",
  "createdAt": "2026-02-03T09:00:00Z",
  "createdBy": "christina.adler@muster-it.example",
  "customerNo": "99999",
  "documentCount": 1284,
  "from": "2025-01-01T00:00:00Z",
  "id": "9b1d3f5b-7c9e-4a1b-8d3f-5b7c9e1a3b5d",
  "sha256": "c4a9e1f7b3d5028e6a4c9f1b7d3e5a2c8f0b6d4e2a9c7f5b1d3e8a6c0f4b2d9e",
  "sizeBytes": 412318720,
  "status": "DONE",
  "tenantName": "DEMO",
  "to": "2025-12-31T23:59:59Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/exports' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"categories":["incoming_document","contract"],"from":"2025-01-01","to":"2025-12-31"}'
```

## An auditor export (tenant:dms:admin)

`GET /api/dms/v1/exports/{id}`

Module: DMS · operationId: `getExport` · Tag: Exports · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Export (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `categories` (array of string, required): Document types included; empty: all
- `createdAt` (string (date-time), required): Start time
- `createdBy` (string, required): Who started the export
- `customerNo` (string, required): Customer number of the tenant
- `documentCount` (integer, required): Documents in the export
- `from` (string (date-time), required): Documents created from
- `id` (string (uuid), required): Export id
- `sizeBytes` (integer (int64), required): Size of the ZIP in bytes
- `status` (string, required): PENDING while it is built (one of `PENDING`, `DONE`, `FAILED`)
- `tenantName` (string, required): Tenant name
- `to` (string (date-time), required): Documents created until
- `completedAt` (string (date-time)): Time the export finished
- `error` (string): Why the export failed
- `sha256` (string): SHA-256 of the ZIP once done

Example 200 answer:

```json
{
  "categories": [
    "incoming_document",
    "outgoing_invoice"
  ],
  "completedAt": "2026-02-03T09:06:41Z",
  "createdAt": "2026-02-03T09:00:00Z",
  "createdBy": "christina.adler@muster-it.example",
  "customerNo": "99999",
  "documentCount": 1284,
  "from": "2025-01-01T00:00:00Z",
  "id": "9b1d3f5b-7c9e-4a1b-8d3f-5b7c9e1a3b5d",
  "sha256": "c4a9e1f7b3d5028e6a4c9f1b7d3e5a2c8f0b6d4e2a9c7f5b1d3e8a6c0f4b2d9e",
  "sizeBytes": 412318720,
  "status": "DONE",
  "tenantName": "DEMO",
  "to": "2025-12-31T23:59:59Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/exports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Download a finished auditor export (tenant:dms:admin)

`GET /api/dms/v1/exports/{id}/download`

Module: DMS · operationId: `downloadExport` · Tag: Exports · Auth: access token (`Authorization: Bearer <accessToken>`)

Streams the ZIP (`dms-export-<id>.zip`); its SHA-256 is the `ETag`. `409` while the export is not `DONE`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** ZIP archive (`application/zip`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/exports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/download' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Document types

## The tenant's document types in their order (tenant:dms:read or tenant:settings:read)

`GET /api/dms/v1/document-types`

Module: DMS · operationId: `listDocumentTypes` · Tag: Document types · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Document types (`application/json`)

Fields of the 200 answer:

- `items` (array of DocumentType, required): The document types in their order
  - `code` (string, required): Code of the type, used as `category`
  - `createdAt` (string (date-time), required): Creation time
  - `isActive` (boolean, required): Only active types can be chosen for uploads
  - `name` (string, required): Display name
  - `platform` (boolean, required): Used by the platform (`mail`, `outgoing_invoice` or assigned to a role); cannot be deleted or deactivated
  - `retentionYears` (integer, required): Retention period of documents of the type in years
  - `sortOrder` (integer, required): Position in the list
  - `updatedAt` (string (date-time), required): Time of the last change
  - `classifierDescription` (string): Tells the document classifier when the type applies; types without one are never chosen (except the type of the Original-Eingangsbeleg) (max length 1000)
  - `defaultFolderId` (string (uuid)): Uploads of this type without a folder are filed here
  - `role` (string): Role the type is assigned to, if any (one of `incoming_original`, `incoming_supplement`)
  - `targetModule` (string): Module that processes classified documents of the type; `none` only files them (one of `none`, `trade.invoice`, `trade.delivery_note`, `trade.order_confirmation`, `hr`)
- `total` (integer, required): Number of types

Example 200 answer:

```json
{
  "items": [
    {
      "classifierDescription": "Eingangsrechnung, Gutschrift oder Rechnungskorrektur eines Lieferanten: Rechnungsnummer, Rechnungsdatum und ein zu zahlender oder zu erstattender Betrag.",
      "code": "incoming_document",
      "createdAt": "2026-01-02T08:00:00Z",
      "defaultFolderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
      "isActive": true,
      "name": "Eingangsbeleg",
      "platform": true,
      "retentionYears": 10,
      "role": "incoming_original",
      "sortOrder": 1,
      "targetModule": "trade.invoice",
      "updatedAt": "2026-01-02T08:00:00Z"
    },
    {
      "classifierDescription": "Lieferschein: begleitet eine Warenlieferung und listet gelieferte Artikel und Mengen, meist ohne Preise und ohne Zahlungsaufforderung.",
      "code": "delivery_note",
      "createdAt": "2026-01-02T08:00:00Z",
      "isActive": true,
      "name": "Lieferschein",
      "platform": false,
      "retentionYears": 8,
      "sortOrder": 3,
      "targetModule": "trade.delivery_note",
      "updatedAt": "2026-01-02T08:00:00Z"
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/document-types' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Set the order of the document types (tenant:settings:write)

`PATCH /api/dms/v1/document-types`

Module: DMS · operationId: `reorderDocumentTypes` · Tag: Document types · Auth: access token (`Authorization: Bearer <accessToken>`)

`order` must name every type of the tenant exactly once; otherwise the list changed meanwhile and nothing is written (`409`).

### Request body

`application/json` (required)

- `order` (array of string, required): Every code, first to last

Example:

```json
{
  "order": [
    "incoming_document",
    "incoming_supplement",
    "delivery_note",
    "order_confirmation",
    "outgoing_invoice",
    "contract",
    "correspondence",
    "mail",
    "other"
  ]
}
```

### Responses

- **204** Saved
- **400** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/dms/v1/document-types' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"order":["incoming_document","incoming_supplement","delivery_note","order_confirmation","outgoing_invoice","contract","correspondence","mail","other"]}'
```

## Create or change a document type (tenant:settings:write)

`PUT /api/dms/v1/document-types/{code}`

Module: DMS · operationId: `upsertDocumentType` · Tag: Document types · Auth: access token (`Authorization: Bearer <accessToken>`)

Without `sortOrder` a new type goes to the end and an existing one keeps its place. Types in
use by the platform (`mail`, `outgoing_invoice` and the types assigned to a role) cannot be deactivated (`422`
on `isActive`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `code` | path | string | yes | Document type code (lower-cased by the server) |

### Request body

`application/json` (required)

- `name` (string, required): Display name (max length 128)
- `retentionYears` (integer, required): Retention period in years (max 30)
- `classifierDescription` (string, nullable): Description for the document classifier; `null` or empty clears it, omitted keeps it (max length 1000)
- `defaultFolderId` (string (uuid), nullable): Default folder; `null` clears it, omitted keeps it
- `isActive` (boolean): Only active types can be chosen for uploads (default `true`)
- `sortOrder` (integer): Position in the list
- `targetModule` (string): Target module; omitted keeps it (`none` for a new type) (one of `none`, `trade.invoice`, `trade.delivery_note`, `trade.order_confirmation`, `hr`)

Example:

```json
{
  "isActive": true,
  "name": "Lieferantenvertrag",
  "retentionYears": 10
}
```

### Responses

- **200** The document type (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `code` (string, required): Code of the type, used as `category`
- `createdAt` (string (date-time), required): Creation time
- `isActive` (boolean, required): Only active types can be chosen for uploads
- `name` (string, required): Display name
- `platform` (boolean, required): Used by the platform (`mail`, `outgoing_invoice` or assigned to a role); cannot be deleted or deactivated
- `retentionYears` (integer, required): Retention period of documents of the type in years
- `sortOrder` (integer, required): Position in the list
- `updatedAt` (string (date-time), required): Time of the last change
- `classifierDescription` (string): Tells the document classifier when the type applies; types without one are never chosen (except the type of the Original-Eingangsbeleg) (max length 1000)
- `defaultFolderId` (string (uuid)): Uploads of this type without a folder are filed here
- `role` (string): Role the type is assigned to, if any (one of `incoming_original`, `incoming_supplement`)
- `targetModule` (string): Module that processes classified documents of the type; `none` only files them (one of `none`, `trade.invoice`, `trade.delivery_note`, `trade.order_confirmation`, `hr`)

Example 200 answer:

```json
{
  "classifierDescription": "Eingangsrechnung, Gutschrift oder Rechnungskorrektur eines Lieferanten: Rechnungsnummer, Rechnungsdatum und ein zu zahlender oder zu erstattender Betrag.",
  "code": "incoming_document",
  "createdAt": "2026-01-02T08:00:00Z",
  "defaultFolderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "isActive": true,
  "name": "Eingangsbeleg",
  "platform": true,
  "retentionYears": 10,
  "role": "incoming_original",
  "sortOrder": 1,
  "targetModule": "trade.invoice",
  "updatedAt": "2026-01-02T08:00:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/dms/v1/document-types/supplier_contract' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"isActive":true,"name":"Lieferantenvertrag","retentionYears":10}'
```

## Delete an unused document type (tenant:settings:write)

`DELETE /api/dms/v1/document-types/{code}`

Module: DMS · operationId: `deleteDocumentType` · Tag: Document types · Auth: access token (`Authorization: Bearer <accessToken>`)

Types used by any document (deleted ones included) and platform types cannot be deleted (`409`); deactivate them instead.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `code` | path | string | yes | Document type code (lower-cased by the server) |

### Responses

- **204** Deleted
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/dms/v1/document-types/supplier_contract' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The types assigned to the Original-Eingangsbeleg and the Zusatzbeleg (tenant:dms:read or tenant:settings:read)

`GET /api/dms/v1/document-type-roles`

Module: DMS · operationId: `getDocumentTypeRoles` · Tag: Document types · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Roles (`application/json`)

Fields of the 200 answer:

- `incomingOriginal` (string, required): Type of the Original-Eingangsbeleg
- `incomingSupplement` (string, required): Type of the Zusatzbeleg

Example 200 answer:

```json
{
  "incomingOriginal": "incoming_document",
  "incomingSupplement": "incoming_supplement"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/document-type-roles' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Assign the types of the Original-Eingangsbeleg and the Zusatzbeleg (tenant:settings:write)

`PUT /api/dms/v1/document-type-roles`

Module: DMS · operationId: `setDocumentTypeRoles` · Tag: Document types · Auth: access token (`Authorization: Bearer <accessToken>`)

Both need an existing, active type, and they must differ (`422`). Moving the
Original-Eingangsbeleg role moves the target module `trade.invoice` along: the new type gets
it when its target was `none`, the previous type gives it up when it had it.

### Request body

`application/json` (required)

- `incomingOriginal` (string, required): Type of the Original-Eingangsbeleg
- `incomingSupplement` (string, required): Type of the Zusatzbeleg

Example:

```json
{
  "incomingOriginal": "incoming_document",
  "incomingSupplement": "incoming_supplement"
}
```

### Responses

- **200** Roles (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `incomingOriginal` (string, required): Type of the Original-Eingangsbeleg
- `incomingSupplement` (string, required): Type of the Zusatzbeleg

Example 200 answer:

```json
{
  "incomingOriginal": "incoming_document",
  "incomingSupplement": "incoming_supplement"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/dms/v1/document-type-roles' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"incomingOriginal":"incoming_document","incomingSupplement":"incoming_supplement"}'
```

# Classification

## Assign a document type by hand (tenant:dms:write)

`PUT /api/dms/v1/documents/{id}/category`

Module: DMS · operationId: `setDocumentCategory` · Tag: Classification · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets the document type (`category`, an active type of the tenant) and with it the retention
period of the type when that is longer (a change of type never shortens the retention, and
it never ends before a WORM lock). It confirms or corrects the document
classifier: the classification is recorded with source `manual`, the document's
`classificationStatus` becomes `confirmed`, the start of its text is kept as example for later
classifications of the tenant, and `dms.document.classified` is published with `final: true`.
Sending the current type confirms it. The platform types – the e-mail original (`mail`),
filed by the mailbox import, and `outgoing_invoice`, filed by trade for issued invoices – and
the type of the Zusatzbeleg are assigned by the platform only: a document neither gets nor
leaves them by hand (`400 invalid` with `field: category`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `category` (string, required): Code of an active document type (max length 64)

Example:

```json
{
  "category": "delivery_note"
}
```

### Responses

- **200** The document (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
- `createdAt` (string (date-time), required): Upload time
- `currentVersion` (integer, required): Current version number
- `customerNo` (string, required): Customer number of the tenant
- `documentNumber` (string, required): Per-tenant, per-year document number
- `extraction` (Extraction, required): Text extraction state of the current version
  - `attempts` (integer, required): Extraction attempts so far
  - `degraded` (boolean, required): At least one page was extracted in degraded quality
  - `pagesProcessed` (integer, required): Pages extracted so far
  - `pagesTotal` (integer, required): Pages of the file
  - `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)
  - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
  - `error` (string): Error message of a failed extraction
  - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
  - `updatedAt` (string (date-time)): Time of the last state change
- `fileName` (string, required): File name of the current version
- `fileSize` (integer (int64), required): Size of the current version
- `id` (string (uuid), required): Document id
- `isArchived` (boolean, required): Same as `isLocked`
- `isEncrypted` (boolean, required): Content is client-side encrypted
- `isLocked` (boolean, required): WORM lock (same as `isArchived`)
- `isPortalVisible` (boolean, required): Visible in the customer portal
- `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
- `mimeType` (string, required): MIME type of the current version
- `retentionYears` (integer, required): Retention period in years (from the document type)
- `s3Bucket` (string, required): Storage bucket of the current version
- `s3Key` (string, required): Storage key of the current version
- `s3Path` (string, required): Same as `s3Key`
- `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
- `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
- `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
- `tenantName` (string, required): Tenant name
- `title` (string, required): Defaults to the file name
- `updatedAt` (string (date-time), required): Time of the last change
- `uploadedBy` (string, required): Who uploaded the document
- `version` (integer, required): Current version number (same as `currentVersion`)
- `category` (string): Document type code
- `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
- `deletedAt` (string (date-time)): Time of the soft delete
- `encryptionAlgorithm` (string): Only for encrypted documents
- `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
- `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
  - `id` (string (uuid), required): Folder id
  - `name` (string, required): Folder name
- `hashSha256` (string): SHA-256 (hex) of the current version
- `links` (array of DocumentLink): Omitted when the document has none
  - `createdAt` (string (date-time), required): Creation time
  - `createdBy` (string, required): Who created the link
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The linked document
  - `id` (string (uuid), required): Link id
  - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
  - `targetId` (string, required): Id of the linked record
  - `targetModule` (string, required): Module of the linked record
  - `targetType` (string, required): Type of the linked record (see TargetType)
  - `tenantName` (string, required): Tenant name
- `lockRetentionUntil` (string (date-time)): End of the WORM lock
- `metadata` (object): Free metadata (JSON object)
- `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
- `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
- `versions` (array of DocumentVersion): Only in the detail and after a version upload
  - `createdAt` (string (date-time), required): Upload time
  - `createdBy` (string, required): Who uploaded the version
  - `customerNo` (string, required): Customer number of the tenant
  - `documentId` (string (uuid), required): The document of the version
  - `fileName` (string, required): File name of the version
  - `fileSize` (integer (int64), required): Size in bytes
  - `id` (string (uuid), required): Version id
  - `mimeType` (string, required): MIME type of the version
  - `s3Path` (string, required): Storage key of the version
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): SHA-256 (hex) of the version
  - `tenantName` (string, required): Tenant name
  - `versionNumber` (integer, required): Version number, from 1
  - `changeSummary` (string): What changed with this version

Example 200 answer:

```json
{
  "category": "incoming_document",
  "classificationStatus": "classified",
  "confidentialLevel": "INTERNAL",
  "createdAt": "2026-09-30T08:40:12Z",
  "currentVersion": 1,
  "customerNo": "99999",
  "documentNumber": "DOC-2026-000042",
  "extraction": {
    "attempts": 1,
    "degraded": false,
    "eInvoice": "ZUGFERD",
    "pagesProcessed": 2,
    "pagesTotal": 2,
    "status": "DONE",
    "updatedAt": "2026-09-30T08:41:03Z"
  },
  "fileName": "RE-482117.pdf",
  "fileSize": 184320,
  "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "folderPath": [
    {
      "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
      "name": "Buchhaltung"
    },
    {
      "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
      "name": "Eingangsrechnungen 2026"
    }
  ],
  "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "isArchived": true,
  "isEncrypted": false,
  "isLocked": true,
  "isPortalVisible": false,
  "legalHold": false,
  "links": [
    {
      "createdAt": "2026-09-30T08:40:12Z",
      "createdBy": "christina.adler@muster-it.example",
      "customerNo": "99999",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
      "relationType": "ATTACHMENT",
      "targetId": "70001",
      "targetModule": "masterdata",
      "targetType": "SUPPLIER",
      "tenantName": "DEMO"
    }
  ],
  "lockRetentionUntil": "2036-12-31T23:59:59Z",
  "metadata": {
    "invoiceNumber": "RE-482117",
    "supplier": "Nordlicht IT-Distribution GmbH"
  },
  "mimeType": "application/pdf",
  "retentionUntil": "2036-12-31T23:59:59Z",
  "retentionYears": 10,
  "s3Bucket": "99999-demo-prod-mbcom-cloud",
  "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
  "scanStatus": "CLEAN",
  "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
  "sizeBytes": 184320,
  "source": "mail",
  "tenantName": "DEMO",
  "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
  "updatedAt": "2026-09-30T08:41:03Z",
  "uploadedBy": "christina.adler@muster-it.example",
  "version": 1
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/category' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"category":"delivery_note"}'
```

## The classification history of a document, oldest first (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/classifications`

Module: DMS · operationId: `listDocumentClassifications` · Tag: Classification · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Classifications (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Classification, required): The classification history, oldest first
  - `category` (string, required): The proposed or chosen document type
  - `confidence` (number, required): Confidence of the proposal (0–1) (max 1)
  - `createdAt` (string (date-time), required): Time of the classification
  - `documentId` (string (uuid), required): Document id
  - `final` (boolean, required): false: a proposal below the threshold that waits for review
  - `id` (integer (int64), required): Entry id
  - `source` (string, required): ai = the classifier model, einvoice = the e-invoice XML, manual = a person (one of `ai`, `einvoice`, `manual`)
  - `targetModule` (string, required): Module that processes documents of the type (one of `none`, `trade.invoice`, `trade.delivery_note`, `trade.order_confirmation`, `hr`)
  - `version` (integer, required): Document version that was classified
  - `actor` (string): Who chose the type (manual only)
  - `method` (string): Kind of model (ai only) (one of `native`, `llm`)
  - `model` (string): Model that answered (ai only)
  - `previousCategory` (string): The type the document had before
  - `reason` (string): Short justification of the model, if given
- `total` (integer, required): Number of entries

Example 200 answer:

```json
{
  "items": [
    {
      "category": "incoming_document",
      "confidence": 1,
      "createdAt": "2026-09-30T08:40:20Z",
      "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
      "final": true,
      "id": 4711,
      "source": "einvoice",
      "targetModule": "trade.invoice",
      "version": 1
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/classifications' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Documents whose proposed type waits for a person (tenant:dms:read)

`GET /api/dms/v1/classifications/review`

Module: DMS · operationId: `listClassificationReview` · Tag: Classification · Auth: access token (`Authorization: Bearer <accessToken>`)

Documents the classifier proposed a type for with a confidence below the tenant's threshold
(`classification.minConfidence`, default 0.85), oldest proposal first (at most 200). Decide
with `setDocumentCategory`.

### Responses

- **200** Documents to review (`application/json`)

Fields of the 200 answer:

- `items` (array of ClassificationReviewItem, required): Documents waiting for review
  - `classifiedAt` (string (date-time), required): Time of the proposal
  - `confidence` (number, required): Confidence of the proposal (max 1)
  - `createdAt` (string (date-time), required): Upload time of the document
  - `documentId` (string (uuid), required): Document id
  - `documentNumber` (string, required): Document number
  - `fileName` (string, required): File name
  - `mimeType` (string, required): MIME type
  - `suggestedCategory` (string, required): The proposed document type
  - `title` (string, required): Document title
  - `category` (string): The current type (unchanged until a person decides)
  - `reason` (string): Short justification of the model, if given
- `total` (integer, required): Number of documents

Example 200 answer:

```json
{
  "items": [
    {
      "category": "incoming_document",
      "classifiedAt": "2026-11-17T15:02:51Z",
      "confidence": 0.61,
      "createdAt": "2026-11-17T15:02:44Z",
      "documentId": "7e9a1c3e-5f7a-4b9c-8d1e-3f5a7b9c1d3e",
      "documentNumber": "DOC-2026-000057",
      "fileName": "Scan_0042.pdf",
      "mimeType": "application/pdf",
      "reason": "Listet gelieferte Artikel und Mengen, aber keinen Zahlbetrag.",
      "suggestedCategory": "delivery_note",
      "title": "Scan_0042"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/classifications/review' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## How classified documents got their type, per type (tenant:dms:read)

`GET /api/dms/v1/classifications/stats`

Module: DMS · operationId: `getClassificationStats` · Tag: Classification · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Counts per document type (`application/json`)

Fields of the 200 answer:

- `items` (array of ClassificationStat, required): One row per document type
  - `automatic` (integer, required): Taken over without review
  - `category` (string, required): Document type code
  - `confirmed` (integer, required): A person confirmed the proposal
  - `corrected` (integer, required): A person chose another type than the proposal
  - `pending` (integer, required): Waiting for review
- `total` (integer, required): Number of rows

Example 200 answer:

```json
{
  "items": [
    {
      "automatic": 212,
      "category": "incoming_document",
      "confirmed": 9,
      "corrected": 3,
      "pending": 1
    },
    {
      "automatic": 48,
      "category": "delivery_note",
      "confirmed": 5,
      "corrected": 2,
      "pending": 1
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/classifications/stats' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Encryption

## List key groups (tenant:dms:read)

`GET /api/dms/v1/key-groups`

Module: DMS · operationId: `listKeyGroups` · Tag: Encryption · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Key groups, by name (`application/json`)

Fields of the 200 answer:

- `items` (array of KeyGroup, required): The key groups of the tenant
  - `algorithm` (string): Key agreement algorithm
  - `createdAt` (string (date-time)): Creation time
  - `createdBy` (string): Who created the group
  - `description` (string): Description
  - `id` (string (uuid)): Key group id
  - `members` (array of object): Members of the group
    - `addedBy` (string): Who added the member
    - `createdAt` (string (date-time)): Time the member was added
    - `userId` (string): User id (e-mail address)
  - `name` (string): Name, unique per tenant
  - `publicKey` (string): Base64 SPKI public key of the group
- `total` (integer, required): Number of key groups

Example 200 answer:

```json
{
  "items": [
    {
      "algorithm": "ECDH-P256",
      "createdAt": "2026-03-10T14:20:00Z",
      "createdBy": "thomas.pfeiffer@muster-it.example",
      "description": "Personalakten und Gehaltsunterlagen",
      "id": "5d7f9b1d-3e5a-4c7b-9d1f-7b9d1f3a5c7e",
      "members": [
        {
          "addedBy": "thomas.pfeiffer@muster-it.example",
          "createdAt": "2026-03-10T14:20:00Z",
          "userId": "thomas.pfeiffer@muster-it.example"
        },
        {
          "addedBy": "thomas.pfeiffer@muster-it.example",
          "createdAt": "2026-03-10T14:22:31Z",
          "userId": "christina.adler@muster-it.example"
        }
      ],
      "name": "Personalabteilung",
      "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexamplePublicKeyOfTheGroupP256xyz"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/key-groups' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a key group with its members (tenant:dms:admin)

`POST /api/dms/v1/key-groups`

Module: DMS · operationId: `createKeyGroup` · Tag: Encryption · Auth: access token (`Authorization: Bearer <accessToken>`)

The group private key is generated in the browser and wrapped for every member (1 to 100); every member must have registered a key. Names are unique per tenant (`409`).

### Request body

`application/json` (required)

- `members` (array of KeyGroupMemberInput, required): Initial members with their share of the group key
  - `ephemeralPublicKey` (string, required): Base64 SPKI P-256 ephemeral public key of the wrap
  - `userId` (string, required): User id (e-mail address); must have registered a key
  - `wrappedGroupPrivateKey` (string, required): The group private key wrapped for the member (base64)
- `name` (string, required): Name, unique per tenant
- `publicKey` (string, required): Base64 SPKI P-256 public key of the group
- `algorithm` (string): Key agreement algorithm (default `"ECDH-P256"`)
- `description` (string): Description

Example:

```json
{
  "algorithm": "ECDH-P256",
  "description": "Personalakten und Gehaltsunterlagen",
  "members": [
    {
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleEphemeralKeyThomas",
      "userId": "thomas.pfeiffer@muster-it.example",
      "wrappedGroupPrivateKey": "ZXhhbXBsZS13cmFwcGVkLWdyb3VwLWtleS1mb3ItdGhvbWFz"
    }
  ],
  "name": "Personalabteilung",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexamplePublicKeyOfTheGroupP256xyz"
}
```

### Responses

- **201** The key group (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `algorithm` (string): Key agreement algorithm
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the group
- `description` (string): Description
- `id` (string (uuid)): Key group id
- `members` (array of object): Members of the group
  - `addedBy` (string): Who added the member
  - `createdAt` (string (date-time)): Time the member was added
  - `userId` (string): User id (e-mail address)
- `name` (string): Name, unique per tenant
- `publicKey` (string): Base64 SPKI public key of the group

Example 201 answer:

```json
{
  "algorithm": "ECDH-P256",
  "createdAt": "2026-03-10T14:20:00Z",
  "createdBy": "thomas.pfeiffer@muster-it.example",
  "description": "Personalakten und Gehaltsunterlagen",
  "id": "5d7f9b1d-3e5a-4c7b-9d1f-7b9d1f3a5c7e",
  "members": [
    {
      "addedBy": "thomas.pfeiffer@muster-it.example",
      "createdAt": "2026-03-10T14:20:00Z",
      "userId": "thomas.pfeiffer@muster-it.example"
    },
    {
      "addedBy": "thomas.pfeiffer@muster-it.example",
      "createdAt": "2026-03-10T14:22:31Z",
      "userId": "christina.adler@muster-it.example"
    }
  ],
  "name": "Personalabteilung",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexamplePublicKeyOfTheGroupP256xyz"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/key-groups' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"algorithm":"ECDH-P256","description":"Personalakten und Gehaltsunterlagen","members":[{"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleEphemeralKeyThomas","userId":"thomas.pfeiffer@muster-it.example","wrappedGroupPrivateKey":"ZXhhbXBsZS13cmFwcGVkLWdyb3VwLWtleS1mb3ItdGhvbWFz"}],"name":"Personalabteilung","publicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexamplePublicKeyOfTheGroupP256xyz"}'
```

## Add a member to a key group (tenant:dms:admin)

`POST /api/dms/v1/key-groups/{id}/members`

Module: DMS · operationId: `addKeyGroupMember` · Tag: Encryption · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `ephemeralPublicKey` (string, required): Base64 SPKI P-256 ephemeral public key of the wrap
- `userId` (string, required): User id (e-mail address); must have registered a key
- `wrappedGroupPrivateKey` (string, required): The group private key wrapped for the member (base64)

Example:

```json
{
  "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleEphemeralKeyChristina",
  "userId": "christina.adler@muster-it.example",
  "wrappedGroupPrivateKey": "ZXhhbXBsZS13cmFwcGVkLWdyb3VwLWtleS1mb3ItY2hyaXN0aW5h"
}
```

### Responses

- **200** The key group (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `algorithm` (string): Key agreement algorithm
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the group
- `description` (string): Description
- `id` (string (uuid)): Key group id
- `members` (array of object): Members of the group
  - `addedBy` (string): Who added the member
  - `createdAt` (string (date-time)): Time the member was added
  - `userId` (string): User id (e-mail address)
- `name` (string): Name, unique per tenant
- `publicKey` (string): Base64 SPKI public key of the group

Example 200 answer:

```json
{
  "algorithm": "ECDH-P256",
  "createdAt": "2026-03-10T14:20:00Z",
  "createdBy": "thomas.pfeiffer@muster-it.example",
  "description": "Personalakten und Gehaltsunterlagen",
  "id": "5d7f9b1d-3e5a-4c7b-9d1f-7b9d1f3a5c7e",
  "members": [
    {
      "addedBy": "thomas.pfeiffer@muster-it.example",
      "createdAt": "2026-03-10T14:20:00Z",
      "userId": "thomas.pfeiffer@muster-it.example"
    },
    {
      "addedBy": "thomas.pfeiffer@muster-it.example",
      "createdAt": "2026-03-10T14:22:31Z",
      "userId": "christina.adler@muster-it.example"
    }
  ],
  "name": "Personalabteilung",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexamplePublicKeyOfTheGroupP256xyz"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/key-groups/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/members' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleEphemeralKeyChristina","userId":"christina.adler@muster-it.example","wrappedGroupPrivateKey":"ZXhhbXBsZS13cmFwcGVkLWdyb3VwLWtleS1mb3ItY2hyaXN0aW5h"}'
```

## Remove a member from a key group (tenant:dms:admin)

`DELETE /api/dms/v1/key-groups/{id}/members/{userId}`

Module: DMS · operationId: `removeKeyGroupMember` · Tag: Encryption · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `userId` | path | string | yes | User id (e-mail address) |

### Responses

- **204** Removed
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/dms/v1/key-groups/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/members/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The tenant's active recovery public key (tenant:dms:read)

`GET /api/dms/v1/recovery-key`

Module: DMS · operationId: `getRecoveryKey` · Tag: Encryption · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Recovery key (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `algorithm` (string): Key agreement algorithm
- `createdAt` (string (date-time)): Time the key was set
- `createdBy` (string): Who set the key
- `fingerprint` (string): SHA-256 (hex) of the public key
- `id` (string (uuid)): Recovery key id
- `publicKey` (string): Base64 SPKI public key

Example 200 answer:

```json
{
  "algorithm": "ECDH-P256",
  "createdAt": "2026-03-10T14:00:00Z",
  "createdBy": "thomas.pfeiffer@muster-it.example",
  "fingerprint": "2d8f4b0e6a1c7f3d9b5e2a8c4f0d6b1e7a3c9f5d2b8e4a0c6f1d7b3e9a5c2f8d",
  "id": "7f9b1d3f-5a7c-4e9b-8d1f-9b1d3f5a7c9e",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleRecoveryPublicKeyP256xyz"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/recovery-key' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Set the tenant's recovery public key (tenant:dms:admin)

`PUT /api/dms/v1/recovery-key`

Module: DMS · operationId: `setRecoveryKey` · Tag: Encryption · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores the public half of the tenant's offline recovery key; encrypted uploads must always include a wrap for it.

### Request body

`application/json` (required)

- `publicKey` (string, required): Base64 SPKI P-256 public key
- `algorithm` (string): Key agreement algorithm (default ECDH-P256) (default `"ECDH-P256"`)

Example:

```json
{
  "algorithm": "ECDH-P256",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleRecoveryPublicKeyP256xyz"
}
```

### Responses

- **200** Recovery key (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `algorithm` (string): Key agreement algorithm
- `createdAt` (string (date-time)): Time the key was set
- `createdBy` (string): Who set the key
- `fingerprint` (string): SHA-256 (hex) of the public key
- `id` (string (uuid)): Recovery key id
- `publicKey` (string): Base64 SPKI public key

Example 200 answer:

```json
{
  "algorithm": "ECDH-P256",
  "createdAt": "2026-03-10T14:00:00Z",
  "createdBy": "thomas.pfeiffer@muster-it.example",
  "fingerprint": "2d8f4b0e6a1c7f3d9b5e2a8c4f0d6b1e7a3c9f5d2b8e4a0c6f1d7b3e9a5c2f8d",
  "id": "7f9b1d3f-5a7c-4e9b-8d1f-9b1d3f5a7c9e",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleRecoveryPublicKeyP256xyz"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/dms/v1/recovery-key' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"algorithm":"ECDH-P256","publicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleRecoveryPublicKeyP256xyz"}'
```

## The caller's key wraps of an encrypted version (tenant:dms:read)

`GET /api/dms/v1/documents/{id}/encryption`

Module: DMS · operationId: `getDocumentEncryption` · Tag: Encryption · Auth: access token (`Authorization: Bearer <accessToken>`)

`400` for unencrypted documents, `403` when the caller holds no wrap (directly or through a key group). Callers with `tenant:dms:admin` also see the recovery wrap.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `version` | query | integer |  | Version number; default the current version |

### Responses

- **200** Envelope (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `alg` (string, required): Content encryption algorithm
- `documentId` (string (uuid), required): Document id
- `groupKeys` (array of GroupKeyShare, required): The caller's shares of the groups the document is wrapped for
  - `algorithm` (string): Key agreement algorithm
  - `ephemeralPublicKey` (string): Base64 SPKI P-256 ephemeral public key of the wrap
  - `groupId` (string (uuid)): Key group id
  - `groupName` (string): Key group name
  - `publicKey` (string): Base64 SPKI public key of the group
  - `wrappedGroupPrivateKey` (string): The group private key wrapped for the caller (base64)
- `iv` (string, required): Initialization vector of the content encryption (base64)
- `versionNumber` (integer, required): Version the wraps belong to
- `wraps` (array of KeyWrap, required): The document key wrapped for the caller and its groups
  - `ephemeralPublicKey` (string, required): Base64 SPKI P-256 public key
  - `recipientId` (string, required): User id (e-mail), key group id or recovery key id
  - `recipientType` (string, required): Who the wrap is for (one of `USER`, `GROUP`, `RECOVERY`)
  - `wrappedDek` (string, required): The document key wrapped with ECDH + AES-GCM (base64)
- `encryptedMetadata` (string): Client-encrypted metadata, if any

Example 200 answer:

```json
{
  "alg": "AES-256-GCM",
  "documentId": "9d1f3b5d-7e9a-4c1d-8f3b-1d3f5b7d9e1a",
  "groupKeys": [
    {
      "algorithm": "ECDH-P256",
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleEphemeralKeyChristina",
      "groupId": "5d7f9b1d-3e5a-4c7b-9d1f-7b9d1f3a5c7e",
      "groupName": "Personalabteilung",
      "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexamplePublicKeyOfTheGroupP256xyz",
      "wrappedGroupPrivateKey": "ZXhhbXBsZS13cmFwcGVkLWdyb3VwLWtleS1mb3ItY2hyaXN0aW5h"
    }
  ],
  "iv": "ZXhhbXBsZS1pdi0xMg==",
  "versionNumber": 1,
  "wraps": [
    {
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleEphemeralKeyDocument",
      "recipientId": "5d7f9b1d-3e5a-4c7b-9d1f-7b9d1f3a5c7e",
      "recipientType": "GROUP",
      "wrappedDek": "ZXhhbXBsZS13cmFwcGVkLWRlay1mb3ItZ3JvdXA"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/encryption' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Configuration

## The module configuration (tenant:dms:read)

`GET /api/dms/v1/config`

Module: DMS · operationId: `getConfig` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

A tenant without configuration gets `{"active": false, "wormCompliance": false}`.

### Responses

- **200** Configuration (`application/json`)

Fields of the 200 answer:

- `active` (boolean): The module is active for the tenant
- `classification` (object): Document classifier of incoming documents (Original-Eingangsbelege); omitted = defaults
  - `enabled` (boolean): The document classifier is on (default `true`)
  - `minConfidence` (number): Proposals from this confidence on are taken over; below it they wait for review (default `0.85`; max 1)
- `defaultRetentionDays` (integer): Default retention in days
- `defaultStorageClass` (string): Default storage class
- `extraction` (object): Text extraction settings; omitted = defaults
  - `enabled` (boolean): Text extraction is on (default `true`)
  - `layoutCategories` (array of string): Document types whose digital pages still go to AI OCR for layout
  - `maxPages` (integer): Page limit per document (default `200`; max 2000)
- `wormCompliance` (boolean): WORM compliance mode

Example 200 answer:

```json
{
  "active": true,
  "classification": {
    "enabled": true,
    "minConfidence": 0.85
  },
  "defaultRetentionDays": 3650,
  "defaultStorageClass": "STANDARD",
  "extraction": {
    "enabled": true,
    "layoutCategories": [
      "delivery_note"
    ],
    "maxPages": 200
  },
  "wormCompliance": true
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Save the module configuration (tenant:settings:write)

`PUT /api/dms/v1/config`

Module: DMS · operationId: `setConfig` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `active` (boolean): The module is active for the tenant
- `classification` (object): Document classifier of incoming documents (Original-Eingangsbelege); omitted = defaults
  - `enabled` (boolean): The document classifier is on (default `true`)
  - `minConfidence` (number): Proposals from this confidence on are taken over; below it they wait for review (default `0.85`; max 1)
- `defaultRetentionDays` (integer): Default retention in days
- `defaultStorageClass` (string): Default storage class
- `extraction` (object): Text extraction settings; omitted = defaults
  - `enabled` (boolean): Text extraction is on (default `true`)
  - `layoutCategories` (array of string): Document types whose digital pages still go to AI OCR for layout
  - `maxPages` (integer): Page limit per document (default `200`; max 2000)
- `wormCompliance` (boolean): WORM compliance mode

Example:

```json
{
  "active": true,
  "classification": {
    "enabled": true,
    "minConfidence": 0.85
  },
  "defaultRetentionDays": 3650,
  "defaultStorageClass": "STANDARD",
  "extraction": {
    "enabled": true,
    "layoutCategories": [
      "delivery_note"
    ],
    "maxPages": 200
  },
  "wormCompliance": true
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `status` (string): Always saved

Example 200 answer:

```json
{
  "status": "saved"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/dms/v1/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"classification":{"enabled":true,"minConfidence":0.85},"defaultRetentionDays":3650,"defaultStorageClass":"STANDARD","extraction":{"enabled":true,"layoutCategories":["delivery_note"],"maxPages":200},"wormCompliance":true}'
```

## Whether the module is active and the state of the extraction queue (tenant:dms:read)

`GET /api/dms/v1/config/status`

Module: DMS · operationId: `getConfigStatus` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Status (`application/json`)

Fields of the 200 answer:

- `active` (boolean): The module is active for the tenant
- `extraction` (object): State of the extraction queue
  - `failedLast24h` (integer): Extractions that failed in the last 24 hours
  - `oldestPendingSeconds` (integer): Age of the oldest queued extraction in seconds
  - `pending` (integer): Queued or running extractions
  - `services` (object): Reachability of the extraction services by name

Example 200 answer:

```json
{
  "active": true,
  "extraction": {
    "failedLast24h": 0,
    "oldestPendingSeconds": 14,
    "pending": 2,
    "services": {
      "ai": "ok",
      "tika": "ok"
    }
  }
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/config/status' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

