Start a process instance (/api/v1)
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("http://localhost:8080/api/v1/process-instances")) .header("Authorization", "Bearer <token>") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString("{ \"processDefinitionId\": \"order-fulfilment\", \"variables\": { \"orderId\": \"A-1042\", \"amount\": 129.5 } }")) .build();HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());const url = 'http://localhost:8080/api/v1/process-instances';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"processDefinitionId":"order-fulfilment","variables":{"orderId":"A-1042","amount":129.5}}'};
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/api/v1/process-instances \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "processDefinitionId": "order-fulfilment", "variables": { "orderId": "A-1042", "amount": 129.5 } }'Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters”Tenant selection. A principal of one tenant may omit it, and if sent it must name that tenant. A principal that may act in several tenants sends it on every request.
Request Bodyrequired
Section titled “Request Bodyrequired”object
At most 4,128,768 bytes of JSON (the 4 MiB record limit less 64 KiB for the rest of the creation record); larger is refused with 400.
object
Start at these elements (elementId) instead of the none start event. Enclosing sub-processes are created; sequence flows, start and boundary events, events after an event-based gateway and elements inside a multi-instance element are refused with 400.
object
Wait (up to 30 seconds, else 504) until the instance has completed, and answer with its root variables at completion in variables. A terminated instance is answered with 409.
Example
{ "processDefinitionId": "order-fulfilment", "variables": { "orderId": "A-1042", "amount": 129.5 }}Responses
Section titled “ Responses ”Process instance admitted
object
Positive signed 64-bit entity key encoded as a JSON string.
Positive signed 64-bit entity key encoded as a JSON string.
Only with awaitCompletion: the root variables at completion.
object
Example
{ "processDefinitionKey": "2251799813685249", "processInstanceKey": "2251799813685262", "processDefinitionId": "order-fulfilment", "processDefinitionVersion": 1}Invalid request
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:invalid-argument", "title": "Bad Request", "status": 400, "detail": "The request is malformed", "instance": "/api/v1/process-instances"}Authentication required
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:unauthorized", "title": "Unauthorized", "status": 401, "detail": "A valid bearer credential is required", "instance": "/api/v1/process-instances"}Headers
Section titled “Headers”The caller lacks the required permission.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:forbidden", "title": "Forbidden", "status": 403, "detail": "The principal lacks the action this route requires", "instance": "/api/v1/process-instances"}Tenant-scoped resource not found
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:not-found", "title": "Not Found", "status": 404, "detail": "The requested resource does not exist", "instance": "/api/v1/process-instances"}Idempotency conflict
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:conflict", "title": "Conflict", "status": 409, "detail": "The idempotency key is already associated with another request", "instance": "/api/v1/process-instances"}Authenticated request exceeds its configured bound
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:payload-too-large", "title": "Payload Too Large", "status": 413, "detail": "The request exceeds the configured size limit", "instance": "/api/v1/process-instances"}Tenant quota exhausted
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:quota-exhausted", "title": "Quota Exhausted", "status": 429, "detail": "The tenant active-instance quota is exhausted", "instance": "/api/v1/process-instances"}Non-leaking internal failure
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:internal", "title": "Internal Server Error", "status": 500, "detail": "The request could not be completed", "instance": "/api/v1/process-instances"}The operation is on the reviewed allow-list of what this deployment mode cannot serve.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:mode-not-supported", "title": "Mode Not Supported", "status": 501, "detail": "POST /api/v1/process-instances is not supported in embedded mode", "instance": "/api/v1/process-instances", "mode": "embedded"}Backpressure or dependency unavailable
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:unavailable", "title": "Service Unavailable", "status": 503, "detail": "The required engine service is not ready", "instance": "/api/v1/process-instances"}