Upload several documents

POST

/v2/documents/batch

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/documents/batch"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
    .method("POST", HttpRequest.BodyPublishers.ofString("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"file\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadataList\"\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/batch';
const form = new FormData();
form.append('files', 'file');
form.append('metadataList', '[ { "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/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form files=@file \
  --form 'metadataList=[ { "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 several files in one request: each file in a part named files, and optionally a part metadataList with a JSON array of metadata objects matched to the files by position (it must have as many entries as there are files, else 400). A file’s metadata may also come from its X-Document-Metadata part header. Every file needs a file name, from its part or its metadata. When every file is stored the answer is 201; when some fail it is 207, with one problem per failed file (its file name, status, title and detail) next to the references of the stored ones. The upload limit applies to the files of the request together.

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).

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

files

required

Array<string>

>= 1 items

metadataList

Array<object>

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

Every document was stored.

application/json

object

createdDocuments

required

Array<object>

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

failedDocuments

required

Array<object>

object

fileName

required

string

status

required

integer

title

required

string

detail

required

string

Example

{
  "createdDocuments": [
    {
      "camunda.document.type": "camunda"
    }
  ]
}

207

Some documents were stored and others failed.

application/json

object

createdDocuments

required

Array<object>

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

failedDocuments

required

Array<object>

object

fileName

required

string

status

required

integer

title

required

string

detail

required

string

Example

{
  "createdDocuments": [
    {
      "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/batch"
}

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

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

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

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/batch is not supported in embedded mode",
  "instance": "/v2/documents/batch",
  "mode": "embedded"
}

Upload several documents

Authorizations

Parameters

Query Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

207

Example

400

Example

401

Example

Headers

403

Example

413

Example

415

Examplegenerated

500

Example

501

Example

Request Body^required

Example^generated