List documents

GET/documents

Lists the documents the token can see, newest first, and returns one page. A token sees documents whose own read or write list holds its user, documents whose write flags its user satisfies, and every document in a folder it can see, deal folders included. Documents in hidden folders are included; send filter[folder_hidden]=false to leave them out. This deliberately differs from the old route, which hid them and applied no read rules. Use GET /documents/{id} for one document. It changes nothing.

Query parameters

limitinteger#
Page size (1–100). Defaults to 25; values are clamped to the range.
Default: 25
cursorstring#
Opaque pagination cursor taken from a prior response's meta.next_cursor.
fieldsstring#
Comma-separated top-level fields to return. id is always returned.
includestring#
Set to permissions to embed who may read and write each document.
sortstring#
Comma-separated fields to sort by: created_at, name or size. Prefix a field with - for descending. Defaults to -created_at. The document id is always the final tiebreak.
filter[q]string#
Documents whose name or description contains this text, ignoring case.
filter[id]string (uuid)#
The document with this id. Takes [in] and [not_in] with a comma-separated list of up to 100 ids.
filter[folder_id]string (uuid)#
Documents directly in this folder. Send filter[folder_id][null]=true for documents in no folder. Takes [in] and [not_in] with a comma-separated list.
filter[deal_id]string (uuid)#
Documents in this deal's folder tree, the deal's root folder included. Takes [in] and [not_in] with a comma-separated list.
filter[owner_id]string (uuid)#
Documents added by this user. Takes [in] and [not_in] with a comma-separated list.
filter[type]string#
Only documents of this kind: binary, image, video, text, csv, doc, sheet, presentation, pdf, file or email. Takes [in] and [not_in] with a comma-separated list.
filter[mime_type]string#
Documents with this content type, such as application/pdf. Takes [in] and [not_in] with a comma-separated list.
filter[status]string#
Only documents in this status: not_validated, not_scanned, failed_scan, file_available, video_processed or watermark_processing. Takes [in] and [not_in] with a comma-separated list.
filter[created_at]string#
Only documents created in a range, written filter[created_at][gte]=2026-10-01. Takes gt, gte, lt and lte.
filter[within_folder_id]string (uuid)#
Documents in this folder or any folder below it, under the same read rules. Takes [eq], [in] (a comma-separated list of at most 50 folder ids; 422 beyond that) and [not_in]. Used with POST /documents/exports to zip whole folders.
filter[folder_hidden]boolean#
Only documents in hidden folders when true, only documents outside hidden folders when false.

Responses

200

The documents.

Document[]

{
  "data": [
    {
      "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "name": "string",
      "folder_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "deal_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "type": "binary",
      "status": "not_validated",
      "mime_type": "string",
      "size": 1,
      "description": "string",
      "metadata": {},
      "owner_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "allow_download": true,
      "apply_watermark": true,
      "masked": true,
      "access": {
        "internal_users": true,
        "deal_managers": true,
        "file_uploaders": true,
        "entrepreneurs": true
      },
      "permissions": {},
      "created_at": "2026-06-12T10:00:00+00:00",
      "updated_at": "2026-06-12T10:00:00+00:00"
    }
  ],
  "meta": {
    "limit": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}

401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error

403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error

422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error

429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl https://your-org-domain/kong/core/api/v2/documents\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"