Skip to main content

Openapi

full width

API docs by Redocly

ZenBPM OpenAPI (0.1.0)

Download OpenAPI specification:Download

API Support: info@pbinitiative.org License: AGPL

REST API for ZenBPM

process-definition

Deploy a new process definition

Request Body schema: multipart/form-data
required
resource
required
string <binary>

BPMN process definition file (.bpmn format only, max 4MB)

Responses

Response samples

Content type
application/json
{
  • "processDefinitionKey": 4503599627370498
}

Get list of process definitions

query Parameters
onlyLatest
boolean
Default: false

If true, returns only the latest version of each process definition grouped by bpmnProcessId

sortBy
string
Enum: "name" "bpmnProcessId" "bpmnProcessName" "version" "key"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort direction

bpmnProcessId
string

Filter by BPMN process ID to get all versions of a specific process

page
integer <int32> >= 1
Default: 1
Example: page=1

Page number (1-based indexing)

size
integer <int32> [ 1 .. 100 ]
Default: 10
Example: size=10

Number of items per page (max 100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 10,
  • "count": 3,
  • "totalCount": 3
}

Get process definition

path Parameters
processDefinitionKey
required
integer <int64>
Example: 4503599627370498

Responses

Response samples

Content type
application/json
{
  • "key": "4503599627370498",
  • "version": 1,
  • "bpmnProcessId": "loan-application",
  • "bpmnData": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bpmn:definitions>\n <bpmn:process id=\"loan-application\" name=\"Loan Application Process\" isExecutable=\"true\">\n ...\n </bpmn:process>\n</bpmn:definitions>\n"
}

process-instance

Create a new process instance

Request Body schema: application/json
required
processDefinitionKey
required
integer <int64>
variables
object
historyTimeToLive
string

Duration for which process instance data are kept in storage after the process instance ends. If omitted the default will be picked up from engine configuration. (1d8h, 1M5d8h)

businessKey
string

Business key of the process instance used mainly for correlating process instance to the business entity.

Responses

Request samples

Content type
application/json
{
  • "processDefinitionKey": 4503599627370498,
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "key": "4503599627370501",
  • "processDefinitionKey": "4503599627370498",
  • "createdAt": "2025-08-22T14:30:25Z",
  • "state": "active",
  • "variables": {
    }
}

Get list of running process instances

query Parameters
processDefinitionKey
integer <int64>
Example: processDefinitionKey=4503599627370498

Key of the process definition

parentProcessInstanceKey
integer <int64>
Example: parentProcessInstanceKey=1603294627315478

Key of the parent process instance

businessKey
string

Business key of the process instance used mainly for correlating process instance to the business entity.

page
integer <int32> >= 1
Default: 1
Example: page=1

Page number (1-based indexing)

size
integer <int32> >= 1
Default: 10
Example: size=10

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "partitions": [
    ],
  • "page": 1,
  • "size": 10,
  • "count": 3,
  • "totalCount": 3
}

Get state of a process instance selected by processInstanceKey

path Parameters
processInstanceKey
required
integer <int64>
Example: 4503599627370501

Responses

Response samples

Content type
application/json
{
  • "key": "4503599627370501",
  • "processDefinitionKey": "4503599627370498",
  • "createdAt": "2025-08-22T14:30:25Z",
  • "state": "active",
  • "variables": {
    }
}

Get list of jobs for a process instance

path Parameters
processInstanceKey
required
integer <int64>
Example: 4503599627370501
query Parameters
page
integer <int32> >= 1
Default: 1
Example: page=1

Page number (1-based indexing)

size
integer <int32> [ 1 .. 100 ]
Default: 10
Example: size=10

Number of items per page (max 100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 10,
  • "count": 2,
  • "totalCount": 2
}

Get list of visited flow elements for a process instance

path Parameters
processInstanceKey
required
integer <int64>
Example: 4503599627370501
query Parameters
page
integer <int32> >= 1
Default: 1
Example: page=1

Page number (1-based indexing)

size
integer <int32> [ 1 .. 100 ]
Default: 10
Example: size=10

Number of items per page (max 100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 10,
  • "count": 3,
  • "totalCount": 3
}

Get list of incidents for a process instance

path Parameters
processInstanceKey
required
integer <int64>
Example: 4503599627370501
query Parameters
page
integer <int32> >= 1
Default: 1
Example: page=1

Page number (1-based indexing)

size
integer <int32> [ 1 .. 100 ]
Default: 10
Example: size=10

Number of items per page (max 100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 10,
  • "count": 2,
  • "totalCount": 2
}

Start a new process instance starting at chosen elements

Request Body schema: application/json
required
processDefinitionKey
required
integer <int64>
variables
object
startingElementIds
required
Array of strings

Allows for a start at chosen element id

Responses

Request samples

Content type
application/json
{
  • "processDefinitionKey": 4503599627370498,
  • "variables": {
    },
  • "startingElementIds": [
    ]
}

Response samples

Content type
application/json
{
  • "key": 0,
  • "processDefinitionKey": 0,
  • "businessKey": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "state": "active",
  • "parentProcessInstanceKey": 0,
  • "variables": { },
  • "activeElementInstances": [
    ]
}

Modify process instance

Request Body schema: application/json
required
processInstanceKey
required
integer <int64>
variables
object

Sets process instance variables.

Array of objects (StartElementInstanceData)

Starts execution token.

Array of objects (TerminateElementInstanceData)

Terminates execution token.

Responses

Request samples

Content type
application/json
{
  • "processInstanceKey": 0,
  • "variables": { },
  • "elementInstancesToStart": [
    ],
  • "elementInstancesToTerminate": [
    ]
}

Response samples

Content type
application/json
{
  • "processInstance": {
    },
  • "activeElementInstances": [
    ]
}

dmn-resource-definition

Deploy a new dmn resource definition

Request Body schema: application/xml
required
string <xml>

Responses

Request samples

Content type
application/xml
<?xml version="1.0" encoding="UTF-8"?>
<definitions>
  <decision id="loan-approval" name="Loan Approval">
    ...
  </decision>
</definitions>

Response samples

Content type
application/json
{
  • "dmnResourceDefinitionKey": 4503599627370495
}

Get list of dmn resource definitions

query Parameters
page
integer <int32> >= 1
Default: 1
Example: page=1

Page number (1-based indexing)

size
integer <int32> [ 1 .. 100 ]
Default: 10
Example: size=10

Number of items per page (max 100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 10,
  • "count": 3,
  • "totalCount": 3
}

Get dmn resource definition

path Parameters
dmnResourceDefinitionKey
required
integer <int64>
Example: 4503599627370495

Responses

Response samples

Content type
application/json
{
  • "key": "4503599627370495",
  • "version": 1,
  • "decisionDefinitionId": "loan-approval",
  • "dmnData": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<definitions>\n <decision id=\"loan-approval\" name=\"Loan Approval\">\n ...\n </decision>\n</definitions>\n"
}

decision-definition

Evaluate latest version of decision definition directly in engine

path Parameters
decisionId
required
string
Example: loan-approval
Request Body schema: application/json
required
bindingType
required
string
Enum: "latest" "deployment" "versionTag"
decisionDefinitionId
string

Can be used in combination with bindingType latest

versionTag
string

Is used in combination with bindingType versionTag

variables
object

Responses

Request samples

Content type
application/json
{
  • "bindingType": "latest",
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "evaluatedDecisions": [
    ],
  • "decisionOutput": {
    }
}

job

Get list of jobs on partitions

query Parameters
jobType
string
Example: jobType=service-task
state
string (JobState)
Enum: "active" "completed" "terminated" "failed"
Example: state=active
page
integer <int32>
Default: 1
Example: page=1
size
integer <int32>
Default: 10
Example: size=10

Responses

Response samples

Content type
application/json
{
  • "partitions": [
    ],
  • "page": 1,
  • "size": 10,
  • "count": 2,
  • "totalCount": 2
}

Complete a job

Request Body schema: application/json
required
jobKey
required
integer <int64>
variables
object

Responses

Request samples

Content type
application/json
{
  • "jobKey": 4503599627370540,
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "Process instance with key 4503599627370501 not found"
}

message

Publish a message

Request Body schema: application/json
required
correlationKey
required
string
messageName
required
string
variables
object

Responses

Request samples

Content type
application/json
{
  • "correlationKey": "011-235-813",
  • "messageName": "payment-received",
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "Process instance with key 4503599627370501 not found"
}

incident

Resolve an incident

path Parameters
incidentKey
required
integer <int64>
Example: 4503599627370530

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "Process instance with key 4503599627370501 not found"
}

test

start a cpu profiler

path Parameters
nodeId
required
string^[a-zA-Z0-9-_]+$

ID of the node to profile

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "Process instance with key 4503599627370501 not found"
}

stop a cpu profiler

path Parameters
nodeId
required
string^[a-zA-Z0-9-_]+$

ID of the node to stop profiling

Responses

Response samples

Content type
application/json
{
  • "pprof": "string"
}

migration

Start a new process instance starting at chosen elements

Request Body schema: application/json
required
processDefinitionKey
required
integer <int64>
variables
object
startingElementIds
required
Array of strings

Allows for a start at chosen element id

Responses

Request samples

Content type
application/json
{
  • "processDefinitionKey": 4503599627370498,
  • "variables": {
    },
  • "startingElementIds": [
    ]
}

Response samples

Content type
application/json
{
  • "key": 0,
  • "processDefinitionKey": 0,
  • "businessKey": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "state": "active",
  • "parentProcessInstanceKey": 0,
  • "variables": { },
  • "activeElementInstances": [
    ]
}

Modify process instance

Request Body schema: application/json
required
processInstanceKey
required
integer <int64>
variables
object

Sets process instance variables.

Array of objects (StartElementInstanceData)

Starts execution token.

Array of objects (TerminateElementInstanceData)

Terminates execution token.

Responses

Request samples

Content type
application/json
{
  • "processInstanceKey": 0,
  • "variables": { },
  • "elementInstancesToStart": [
    ],
  • "elementInstancesToTerminate": [
    ]
}

Response samples

Content type
application/json
{
  • "processInstance": {
    },
  • "activeElementInstances": [
    ]
}