Upload a document

POST

/v2/documents

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/documents"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
    .method("POST", HttpRequest.BodyPublishers.ofString("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"file\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\nContent-Type: application/json\r\n\r\n{ \"contentType\": \"example\", \"fileName\": \"example\", \"expiresAt\": \"2026-04-15T12:00:00Z\", \"size\": 1, \"processDefinitionId\": \"example\", \"processInstanceKey\": \"example\", \"customProperties\": {} }\r\n-----011000010111000001101001--\r\n"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'http://localhost:8080/v2/documents';
const form = new FormData();
form.append('file', 'file');
form.append('metadata', '{ "contentType": "example", "fileName": "example", "expiresAt": "2026-04-15T12:00:00Z", "size": 1, "processDefinitionId": "example", "processInstanceKey": "example", "customProperties": {} }');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:8080/v2/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@file \
  --form 'metadata={ "contentType": "example", "fileName": "example", "expiresAt": "2026-04-15T12:00:00Z", "size": 1, "processDefinitionId": "example", "processInstanceKey": "example", "customProperties": {} }'

Available inEmbeddedBundledCluster

AuthAuthenticated Bearer token or console session with X-CSRF-Token · requires document:create

Stores one file and answers its document reference, which apps put into process variables and pass back to download the file. The request is multipart/form-data with the file in the part file and optional metadata (JSON) in the part metadata. The content type and file name come from the metadata, else from the file part; the size is always the stored size. documentId names the document (1 to 256 ASCII letters, digits and - _ .; batch is reserved); without it a new id is generated, and an id that already exists in the tenant answers 409. expiresAt must lie in the future; without it the store-wide default time to live applies, if one is set. The files of one request together may hold at most the configured upload limit (default 10 MiB), else 413. A body that is not multipart answers 415. Without a configured document store every document operation answers 501.

Authorizations

Parameters

Query Parameters

storeId

string

The store id from the reference (in-memory, local or s3). Another value answers 404 (400 on an upload).

documentId

string

>= 1 characters <= 256 characters /^[A-Za-z0-9._-]+$/

The id of the new document. Generated when absent.

Header Parameters

x-tenant-id

string

>= 1 characters

Tenant selection. A principal bound to one tenant may omit it; if sent, it must equal that tenant (403 otherwise). A principal that may act in several tenants must send it on every request: without it the request is refused with 400, and a tenant it may not act in is refused with 403.

Request Body^required

multipart/form-data

object

file

required

string format: binary

metadata

What an upload says about a document. Unknown properties are refused with 400.

object

contentType

string

fileName

string

expiresAt

Must lie in the future.

string format: date-time

size

Accepted and ignored; the stored size is the content’s.

integer format: int64

processDefinitionId

string

processInstanceKey

A process instance key as a decimal string.

string

customProperties

object

key

additional properties

any

Responses

201

The document was stored.

application/json

A document reference, as apps store it in process variables.

object

camunda.document.type

required

The document-type discriminator; always this value.

string

Allowed values: camunda

storeId

required

string

documentId

required

string

contentHash

required

The lower-case hex SHA-256 of the content.

string

metadata

required

object

contentType

required

string

fileName

required

string

size

required

integer format: int64

expiresAt

required

string | null format: date-time

processDefinitionId

required

string | null

processInstanceKey

required

string | null

customProperties

required

object

key

additional properties

any

Example

{
  "camunda.document.type": "camunda"
}

400

The request is malformed, or it uses a property or filter this release does not support.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:invalid-argument",
  "title": "Bad Request",
  "status": 400,
  "detail": "entity key must be a positive int64 string",
  "instance": "/v2/process-instances/0"
}

401

No valid credential was presented.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A valid bearer credential is required",
  "instance": "/v2/documents"
}

Headers

WWW-Authenticate

string

Allowed value: Bearer

403

The caller lacks the required permission, a tenant named in the request is not the caller’s tenant, or a cookie write has no valid CSRF token.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The principal lacks the action this route requires",
  "instance": "/v2/documents"
}

409

A document with this id already exists in the caller’s tenant.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The idempotency key is already associated with another request",
  "instance": "/v2/documents"
}

413

The body exceeds the configured request-size bound.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:payload-too-large",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "The request exceeds the configured size limit",
  "instance": "/v2/documents"
}

415

The request body is not multipart/form-data.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "mode": "example"
}

500

An internal failure. The details are never exposed.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:internal",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The request could not be completed",
  "instance": "/v2/documents"
}

501

No document store is configured on this engine (problem type urn:bpm:error:document-store-not-configured).

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:mode-not-supported",
  "title": "Mode Not Supported",
  "status": 501,
  "detail": "POST /v2/documents is not supported in embedded mode",
  "instance": "/v2/documents",
  "mode": "embedded"
}

Upload a document

Authorizations

Parameters

Query Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Example

401

Example

Headers

403

Example

409

Example

413

Example

415

Examplegenerated

500

Example

501

Example

Request Body^required

Example^generated