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

Get running and incident counts per BPMN element

path Parameters
processDefinitionKey
required
integer <int64>
Example: 4503599627370498

Responses

Response samples

Content type
application/json
{
  • "partitions": [
    ]
}

Get process definition statistics

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

Page number (1-based indexing)

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

Number of items per page (max 100)

onlyLatest
boolean
Default: false

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

bpmnProcessIdIn
Array of strings

Filter by BPMN process ID

bpmnProcessDefinitionKeyIn
Array of integers <int64> [ items <int64 > ]

Filter by process definition key

name
string

Filter by name (partial match)

sortBy
string
Enum: "name" "bpmnProcessId" "version" "instanceCount" "incidentCount"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort direction

Responses

Response samples

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

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

bpmnProcessId
string

Filter by BPMN process ID (returns instances across all versions)

sortBy
string
Enum: "createdAt" "key" "state"

Sort field (applies globally across partitions)

sortOrder
string
Enum: "asc" "desc"

Sort direction

createdFrom
string <date-time>

Filter: created after this date

createdTo
string <date-time>

Filter: created before this date

state
string
Enum: "active" "completed" "terminated" "failed"

Filter by state

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
state
string
Enum: "resolved" "unresolved"
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
}

Update process instance variables

path Parameters
processInstanceKey
required
integer <int64>
Example: 4503599627370501
Request Body schema: application/json
required
variables
required
object

Responses

Request samples

Content type
application/json
{
  • "variables": {
    }
}

Response samples

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

Delete a process instance variable

path Parameters
processInstanceKey
required
integer <int64>
Example: 4503599627370501
variableName
required
string

Responses

Response samples

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

Cancels a process instance

path Parameters
processInstanceKey
required
integer <int64>
Example: 4503599627370501

Responses

Response samples

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

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,
  • "bpmnProcessId": "string",
  • "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)

onlyLatest
boolean
Default: false

If true, returns only the latest version of each DMN resource definition grouped by dmnResourceDefinitionId

sortBy
string
Enum: "dmnDefinitionName" "dmnResourceDefinitionId" "version" "key"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort direction

dmnResourceDefinitionId
string

Filter by DMN resource definition ID to get all versions

dmnDefinitionName
string

Filter by name (partial match)

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,
  • "dmnResourceDefinitionId": "loan-approval",
  • "dmnDefinitionName": "Loan Approval Decision",
  • "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"
dmnResourceDefinitionId
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
assignee
string

Filter by assignee

processInstanceKey
integer <int64>

Filter by process instance

page
integer <int32>
Default: 1
Example: page=1
size
integer <int32>
Default: 10
Example: size=10
sortBy
string
Enum: "createdAt" "key" "type" "state"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort direction

Responses

Response samples

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

Get job details

path Parameters
jobKey
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "key": 0,
  • "elementId": "string",
  • "type": "string",
  • "processInstanceKey": 0,
  • "state": "active",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "variables": { },
  • "assignee": "string"
}

Complete a job

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

Responses

Request samples

Content type
application/json
{
  • "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 pprof server

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

ID of the node to start pprof server on

Responses

Response samples

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

stop pprof server

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

ID of the node to stop pprof server on

Responses

Response samples

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

decision-instance

Get list of decision instances

query Parameters
dmnResourceDefinitionKey
integer <int64>

Filter by DMN resource definition key

dmnResourceDefinitionId
string

Filter by DMN resource definition ID

processInstanceKey
integer <int64>

Filter by process instance

evaluatedFrom
string <date-time>

Filter: evaluated after this date

evaluatedTo
string <date-time>

Filter: evaluated before this date

page
integer <int32> >= 1
Default: 1

Page number (1-based indexing)

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

Number of items per page (max 100)

sortBy
string
Enum: "evaluatedAt" "key"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort direction

Responses

Response samples

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

Get decision instance details

path Parameters
decisionInstanceKey
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "key": 0,
  • "dmnResourceDefinitionKey": 0,
  • "processInstanceKey": 0,
  • "flowElementInstanceKey": 0,
  • "evaluatedAt": "2019-08-24T14:15:22Z",
  • "evaluatedDecisions": [
    ],
  • "decisionOutput": "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,
  • "bpmnProcessId": "string",
  • "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": [
    ]
}