## 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"
```
