Openapi

full width

• process-definition
  • postDeploy a new process definition
  • getGet list of process definitions
  • getGet process definition
• process-instance
  • postCreate a new process instance
  • getGet list of running process instances
  • getGet state of a process instance selected by processInstanceKey
  • getGet list of jobs for a process instance
  • getGet list of activities for a process instance
  • getGet list of visited flow elements for a process instance
  • getGet list of incidents for a process instance
• decision-definition
  • postDeploy a new decision definition
  • getGet list of decision definitions
  • getGet decision definition
• decision
  • postEvaluate latest version of decision directly in engine
• job
  • getGet list of jobs on partitions
  • postComplete a job
• message
  • postPublish a message
• incident
  • postResolve an incident
• test
  • poststart a cpu profiler
  • poststop a cpu profiler

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: application/xml

required

string <xml>

Responses

http://localhost:8080/v1/process-definitions

Request samples

• Payload
• curl

Content type

application/xml

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions>
  <bpmn:process id="loan-application" name="Loan Application Process" isExecutable="true">
    ...
  </bpmn:process>
</bpmn:definitions>

Response samples

• 201
• 400
• 409
• 502

Content type

application/json

{

• "processDefinitionKey": "4503599627370498"

}

Get list of process definitions

Responses

http://localhost:8080/v1/process-definitions

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-definitions

Response samples

• 200
• 500

Content type

application/json

{

• "items": [

  • {

    • "key": "4503599627370498",
    • "version": 1,
    • "bpmnProcessId": "loan-application"

    },
  • {

    • "key": "4503599627370499",
    • "version": 2,
    • "bpmnProcessId": "loan-application"

    },
  • {

    • "key": "4503599627370500",
    • "version": 1,
    • "bpmnProcessId": "credit-check"

    }

  ],
• "offset": 0,
• "size": 10,
• "count": 3

}

Get process definition

path Parameters

processDefinitionKey required

string^\d{15,20}$ Example: 4503599627370498

Responses

http://localhost:8080/v1/process-definitions/{processDefinitionKey}

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-definitions/123456789

Response samples

• 200
• 400
• 500

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	string^\d{15,20}$
variables	object

Responses

http://localhost:8080/v1/process-instances

Request samples

• Payload
• curl

Content type

application/json

{

• "processDefinitionKey": "4503599627370498",
• "variables": {

  • "customerId": "customer-456",
  • "amount": 1000,
  • "applicationDate": "2025-08-22"

  }

}

Response samples

• 201
• 400
• 500
• 502

Content type

application/json

{

• "key": "4503599627370501",
• "processDefinitionKey": "4503599627370498",
• "createdAt": "2025-08-22T14:30:25Z",
• "state": "active",
• "variables": {

  • "customerId": "customer-456",
  • "amount": 1000,
  • "applicationDate": "2025-08-22"

  }

}

Get list of running process instances

query Parameters

processDefinitionKey required	string^\d{15,20}$ Example: processDefinitionKey=4503599627370498 Key of the process definition
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

http://localhost:8080/v1/process-instances

Request samples

• curl

curl -X GET "http://localhost:8080/v1/process-instances?processDefinitionKey=123456789&page=1&size=10"

Response samples

• 200
• 400
• 500
• 502

Content type

application/json

{

• "partitions": [

  • {

    • "partition": 1,
    • "items": [

      • {

        • "key": "4503599627370501",
        • "processDefinitionKey": "4503599627370498",
        • "createdAt": "2025-08-22T14:30:25Z",
        • "state": "active",
        • "variables": {

          • "customerId": "customer-456",
          • "amount": 1000,
          • "applicationDate": "2025-08-22"

          }

        },
      • {

        • "key": "4503599627370505",
        • "processDefinitionKey": "4503599627370498",
        • "createdAt": "2025-08-22T15:10:12Z",
        • "state": "active",
        • "variables": {

          • "customerId": "customer-789",
          • "amount": 5000,
          • "applicationDate": "2025-08-22"

          }

        }

      ]

    },
  • {

    • "partition": 2,
    • "items": [

      • {

        • "key": "9007199254740992",
        • "processDefinitionKey": "4503599627370498",
        • "createdAt": "2025-08-22T15:45:33Z",
        • "state": "active",
        • "variables": {

          • "customerId": "customer-101",
          • "amount": 7500,
          • "applicationDate": "2025-08-22"

          }

        }

      ]

    }

  ],
• "page": 1,
• "size": 10,
• "count": 3

}

Get state of a process instance selected by processInstanceKey

path Parameters

processInstanceKey required

string^\d{15,20}$ Example: 4503599627370501

Responses

http://localhost:8080/v1/process-instances/{processInstanceKey}

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-instances/123456789

Response samples

• 200
• 400
• 500
• 502

Content type

application/json

{

• "key": "4503599627370501",
• "processDefinitionKey": "4503599627370498",
• "createdAt": "2025-08-22T14:30:25Z",
• "state": "active",
• "variables": {

  • "customerId": "customer-456",
  • "amount": 1000,
  • "applicationDate": "2025-08-22",
  • "taskAssignee": "john.doe",
  • "currentStatus": "Application review"

  }

}

Get list of jobs for a process instance

path Parameters

processInstanceKey required

string^\d{15,20}$ Example: 4503599627370501

Responses

http://localhost:8080/v1/process-instances/{processInstanceKey}/jobs

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-instances/123456789/jobs

Response samples

• 200
• 400
• 500
• 502

Content type

application/json

{

• "items": [

  • {

    • "key": "4503599627370510",
    • "elementId": "Task_CheckApplication",
    • "type": "user-task",
    • "processInstanceKey": "4503599627370501",
    • "state": "active",
    • "createdAt": "2025-08-22T14:30:26Z",
    • "variables": {

      • "formKey": "loan-application-form",
      • "assignee": "john.doe"

      }

    },
  • {

    • "key": "4503599627370511",
    • "elementId": "Task_CreditCheck",
    • "type": "service-task",
    • "processInstanceKey": "4503599627370501",
    • "state": "completed",
    • "createdAt": "2025-08-22T14:32:15Z",
    • "variables": {

      • "result": "approved",
      • "score": 85

      }

    }

  ],
• "offset": 0,
• "size": 10,
• "count": 2

}

Get list of activities for a process instance

path Parameters

processInstanceKey required

string^\d{15,20}$ Example: 4503599627370501

Responses

http://localhost:8080/v1/process-instances/{processInstanceKey}/activities

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-instances/123456789/activities

Response samples

• 200

Content type

application/json

{

• "items": [

  • {

    • "key": "4503599627370520",
    • "processInstanceKey": "4503599627370501",
    • "processDefinitionKey": "4503599627370498",
    • "createdAt": "2025-08-22T14:30:26Z",
    • "state": "completed",
    • "elementId": "StartEvent_1",
    • "bpmnElementType": "startEvent"

    },
  • {

    • "key": "4503599627370521",
    • "processInstanceKey": "4503599627370501",
    • "processDefinitionKey": "4503599627370498",
    • "createdAt": "2025-08-22T14:30:27Z",
    • "state": "active",
    • "elementId": "Task_CheckApplication",
    • "bpmnElementType": "userTask"

    }

  ],
• "offset": 0,
• "size": 10,
• "count": 2

}

Get list of visited flow elements for a process instance

path Parameters

processInstanceKey required

string^\d{15,20}$ Example: 4503599627370501

Responses

http://localhost:8080/v1/process-instances/{processInstanceKey}/history

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-instances/123456789/history

Response samples

• 200
• 400
• 502

Content type

application/json

{

• "items": [

  • {

    • "key": "4503599627370525",
    • "elementId": "StartEvent_1",
    • "processInstanceKey": "4503599627370501",
    • "createdAt": "2025-08-22T14:30:26Z"

    },
  • {

    • "key": "4503599627370526",
    • "elementId": "Flow_1",
    • "processInstanceKey": "4503599627370501",
    • "createdAt": "2025-08-22T14:30:26Z"

    },
  • {

    • "key": "4503599627370527",
    • "elementId": "Task_CheckApplication",
    • "processInstanceKey": "4503599627370501",
    • "createdAt": "2025-08-22T14:30:27Z"

    }

  ],
• "offset": 0,
• "size": 10,
• "count": 3

}

Get list of incidents for a process instance

path Parameters

processInstanceKey required

string^\d{15,20}$ Example: 4503599627370501

Responses

http://localhost:8080/v1/process-instances/{processInstanceKey}/incidents

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-instances/123456789/incidents

Response samples

• 200
• 400
• 502

Content type

application/json

{

• "items": [

  • {

    • "key": "4503599627370530",
    • "elementInstanceKey": "4503599627370521",
    • "elementId": "Task_CheckApplication",
    • "processInstanceKey": "4503599627370501",
    • "message": "Failed to assign task: User not found",
    • "createdAt": "2025-08-22T14:35:10Z",
    • "executionToken": "123456"

    },
  • {

    • "key": "4503599627370531",
    • "elementInstanceKey": "4503599627370522",
    • "elementId": "Task_CreditCheck",
    • "processInstanceKey": "4503599627370501",
    • "message": "External service unavailable",
    • "createdAt": "2025-08-22T14:36:22Z",
    • "resolvedAt": "2025-08-22T14:45:18Z",
    • "executionToken": "123457"

    }

  ],
• "offset": 0,
• "size": 10,
• "count": 2

}

decision-definition

Deploy a new decision definition

Request Body schema: application/xml

required

string <xml>

Responses

http://localhost:8080/v1/decision-definitions

Request samples

• Payload
• curl

Content type

application/xml

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

Response samples

• 201
• 400
• 409
• 502

Content type

application/json

{

• "decisionDefinitionKey": "4503599627370495"

}

Get list of decision definitions

Responses

http://localhost:8080/v1/decision-definitions

Request samples

• curl

curl -X GET http://localhost:8080/v1/decision-definitions

Response samples

• 200
• 502

Content type

application/json

{

• "items": [

  • {

    • "key": "4503599627370495",
    • "version": 1,
    • "decisionDefinitionId": "loan-approval"

    },
  • {

    • "key": "4503599627370496",
    • "version": 2,
    • "decisionDefinitionId": "loan-approval"

    },
  • {

    • "key": "4503599627370497",
    • "version": 1,
    • "decisionDefinitionId": "credit-score-check"

    }

  ],
• "offset": 0,
• "size": 10,
• "count": 3

}

Get decision definition

path Parameters

decisionDefinitionKey required

string^\d{15,20}$ Example: 4503599627370495

Responses

http://localhost:8080/v1/decision-definitions/{decisionDefinitionKey}

Request samples

• curl

curl -X GET http://localhost:8080/v1/decision-definitions/123456789

Response samples

• 200
• 400
• 502

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

Evaluate latest version of decision 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

http://localhost:8080/v1/decisions/{decisionId}/evaluate

Request samples

• Payload
• curl

Content type

application/json

{

• "bindingType": "latest",
• "variables": {

  • "age": 25,
  • "income": 50000

  }

}

Response samples

• 200
• 500

Content type

application/json

{

• "evaluatedDecisions": [

  • {

    • "decisionId": "loan-approval",
    • "decisionName": "Loan Approval",
    • "decisionType": "DECISION_TABLE",
    • "decisionDefinitionVersion": 1,
    • "decisionDefinitionKey": "4503599627370495",
    • "decisionDefinitionId": "loan-approval",
    • "matchedRules": [

      • {

        • "ruleId": "rule1",
        • "ruleIndex": 0,
        • "evaluatedOutputs": [

          • {

            • "outputId": "output1",
            • "outputName": "approved",
            • "outputValue": {

              • "approved": true

              }

            }

          ]

        }

      ],
    • "decisionOutput": {

      • "approved": true

      },
    • "evaluatedInputs": [

      • {

        • "inputId": "input1",
        • "inputName": "Age",
        • "inputExpression": "age",
        • "inputValue": {

          • "age": 25

          }

        },
      • {

        • "inputId": "input2",
        • "inputName": "Income",
        • "inputExpression": "income",
        • "inputValue": {

          • "income": 50000

          }

        }

      ]

    }

  ],
• "decisionOutput": {

  • "approved": true

  }

}

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

http://localhost:8080/v1/jobs

Request samples

• curl

curl -X GET "http://localhost:8080/v1/jobs?jobType=service-task&state=active&page=1&size=10"

Response samples

• 200
• 500
• 502

Content type

application/json

{

• "partitions": [

  • {

    • "partition": 1,
    • "items": [

      • {

        • "key": "4503599627370540",
        • "elementId": "Task_ProcessPayment",
        • "type": "service-task",
        • "processInstanceKey": "4503599627370501",
        • "state": "active",
        • "createdAt": "2025-08-22T15:10:26Z",
        • "variables": {

          • "paymentDetails": {

            • "amount": 1000,
            • "currency": "USD",
            • "method": "credit-card"

            }

          }

        }

      ]

    },
  • {

    • "partition": 2,
    • "items": [

      • {

        • "key": "9007199254740995",
        • "elementId": "Task_SendNotification",
        • "type": "service-task",
        • "processInstanceKey": "9007199254740992",
        • "state": "active",
        • "createdAt": "2025-08-22T15:46:33Z",
        • "variables": {

          • "notificationType": "email",
          • "recipient": "customer@example.com"

          }

        }

      ]

    }

  ],
• "page": 1,
• "size": 10,
• "count": 2

}

Complete a job

Request Body schema: application/json

required

jobKey required	string^\d{15,20}$
variables	object

Responses

http://localhost:8080/v1/jobs

Request samples

• Payload
• curl

Content type

application/json

{

• "jobKey": "4503599627370540",
• "variables": {

  • "result": "success",
  • "transactionId": "tx-789-xyz",
  • "processedAt": "2025-08-22T15:15:30Z"

  }

}

Response samples

• 400
• 502

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^\d{15,20}$
messageName required	string
variables	object

Responses

http://localhost:8080/v1/messages

Request samples

• Payload
• curl

Content type

application/json

{

• "processInstanceKey": "4503599627370501",
• "messageName": "payment-received",
• "variables": {

  • "paymentId": "pay-123-abc",
  • "amount": 1000,
  • "currency": "USD",
  • "receivedAt": "2025-08-22T16:25:10Z"

  }

}

Response samples

• 400
• 502

Content type

application/json

{

• "code": "NOT_FOUND",
• "message": "Process instance with key 4503599627370501 not found"

}

incident

Resolve an incident

path Parameters

incidentKey required

string^\d{15,20}$ Example: 4503599627370530

Responses

http://localhost:8080/v1/incidents/{incidentKey}/resolve

Request samples

• curl

curl -X POST http://localhost:8080/v1/incidents/123456789/resolve

Response samples

• 400
• 502

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

http://localhost:8080/v1/tests/{nodeId}/start-cpu-profile

Response samples

• 500

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

http://localhost:8080/v1/tests/{nodeId}/stop-cpu-profile

Response samples

• 200
• 500

Content type

application/json

{

• "pprof": "string"

}