Create a document

POST/documents

Adds a document to a folder. Send JSON with name, folder_id and exactly one source: key (from POST /documents/upload-token), content_base64 (an image), or vimeo_id or video_url (a video; no file is stored). Or send multipart/form-data with file. Over post_max_size (20 MB default): 413. A used name is numbered. Needs write access to the folder, else 403; 409 document_key_taken, folder_locked, folder_deleted. dry_run previews JSON only. Emits document.created after commit; no email. DELETE /documents/{id} undoes it.

Query parameters

dry_runboolean#
Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

Idempotency-Keystring#
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required · DocumentCreate

keystring#
The storage key that POST /documents/upload-token returned for the uploaded file, echoed back unchanged.
content_base64string#
An image as base64, raw or as a data:image/<type>;base64, URI, one unbroken string with no spaces or line breaks. PNG, JPEG, GIF or WebP, up to 10 MiB decoded and 50 million pixels, checked by content. A name without an extension gets the image's; a different extension is 422.
vimeo_idstring#
A Vimeo video id, digits only; leading zeros are dropped and zero is refused. The document is a video that stores no file; Vimeo is not contacted. A video registers once: its id stays taken after the document is deleted.
video_urlstring#
An https link to a Vimeo video on vimeo.com, www.vimeo.com or player.vimeo.com, as vimeo.com/ or .../video/. Its id is registered as for vimeo_id. Showcase, album and channel links, and any other scheme or host, are 422.
namestringRequired#
The document's name. A name already used in the folder is numbered.
folder_idstring (uuid)Required#
The folder to put it in. It must be a folder you can see.
descriptionstring | null#
A note kept with the document.
metadataobject | null#
Free-form key-value data kept with the document.

{
  "key": "api-suite/42/5e6f7081-92a3-4b4c-9d6e-7f8091a2b3c4.pdf",
  "name": "term-sheet.pdf",
  "folder_id": "071829a3-4b5c-4d6e-8f90-1a2b3c4d5e6f"
}

Responses

201

The document was created.

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"
  }
}

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

409

The request conflicts with existing state (error.code = conflict), e.g. a compliance flow with the requested name already exists.

Error

413

The request body is over the server's size limit (error.code = payload_too_large). Nothing was read or stored.

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 -X POST https://your-org-domain/kong/core/api/v2/documents\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "key": "api-suite/42/5e6f7081-92a3-4b4c-9d6e-7f8091a2b3c4.pdf",
  "name": "term-sheet.pdf",
  "folder_id": "071829a3-4b5c-4d6e-8f90-1a2b3c4d5e6f"
}'