API docs by Redocly

go-bpmn HTTP API (v0.1.0)

Download OpenAPI specification:

API to interact with a process engine via HTTP.

Elements

An element represents a BPMN element of a process.

Query elements

Performs an element query.

Authorizations:
ApiKeyAuth
query Parameters
offset
integer <int32>

The number of results to skip, before returning any result. If offset is 0, no results are skipped.

limit
integer <int32>

Maximum number of results to return. If limit is 0, all results are returned.

Request Body schema: application/json
processId
integer <int32>

Process filter.

Responses

Request samples

Content type
application/json
{
  • "processId": 0
}

Response samples

Content type
application/json
{
  • "count": 4,
  • "results": [
    ]
}

Element instances

An element instance is an instance of a BPMN element in the scope of an process instance.

Query element instances

Performs an element instance query.

Authorizations:
ApiKeyAuth
query Parameters
offset
integer <int32>

The number of results to skip, before returning any result. If offset is 0, no results are skipped.

limit
integer <int32>

Maximum number of results to return. If limit is 0, all results are returned.

Request Body schema: application/json
partition
string <date>

Partition filter.

id
integer <int32>

Element instance filter.

processId
integer <int32>

Process filter.

processInstanceId
integer <int32>

Process instance filter.

bpmnElementId
string
states
Array of strings (InstanceState) <= 7 items unique
Items Enum: "CANCELED" "CREATED" "ENDED" "QUEUED" "STARTED" "SUSPENDED" "TERMINATED"

States to include.

Responses

Request samples

Content type
application/json
{
  • "partition": "2025-05-01",
  • "processInstanceId": 576
}

Response samples

Content type
application/json
{
  • "count": 3,
  • "results": [
    ]
}

Get element variables

Gets variables of an active or ended element instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

query Parameters
names
string
Examples: names=a,b,c

Comma separated list of variables to include.

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "variables": {
    }
}

Set element variables

Sets or deletes variables of an active element instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

Request Body schema: application/json
required
object

Variables to set or delete. For a variable deletion, no value must be provided.

workerId
required
string

ID of the worker that set the variables.

Responses

Request samples

Content type
application/json
Example
{
  • "variables": {
    },
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/problem+json
{
  • "status": 400,
  • "type": "VALIDATION",
  • "title": "invalid request body",
  • "detail": "failed to validate request body",
  • "errors": [
    ]
}

Incidents

An incident represents a failed job or task, which has no more retries left. An incident is related to either a job or a task.

Query incidents

Performs an incident query.

Authorizations:
ApiKeyAuth
query Parameters
offset
integer <int32>

The number of results to skip, before returning any result. If offset is 0, no results are skipped.

limit
integer <int32>

Maximum number of results to return. If limit is 0, all results are returned.

Request Body schema: application/json
partition
string <date>

Partition filter.

id
integer <int32>

Incident filter.

jobId
integer <int32>

Job filter.

processInstanceId
integer <int32>

Process instance filter.

taskId
integer <int32>

Process filter.

Responses

Request samples

Content type
application/json
{
  • "partition": "2019-08-24",
  • "id": 0,
  • "jobId": 0,
  • "processInstanceId": 0,
  • "taskId": 0
}

Response samples

Content type
application/json
{
  • "count": 1,
  • "results": [
    ]
}

Resolve incident

Resolves a job or task related incident.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

Request Body schema: application/json
retryCount
integer <int32> >= 1

Number of retries the newly created job or task has left.

retryTimer
string

Duration until the retry job or task becomes due.

workerId
required
string

ID of the worker that resolved the incident

Responses

Request samples

Content type
application/json
{
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/problem+json
{
  • "status": 404,
  • "type": "NOT_FOUND",
  • "title": "failed to resolve incident",
  • "detail": "incident 2025-05-01/2 could not be found"
}

Jobs

A job is a unit of work related to an element instance, which must be locked, executed and completed by a worker.

Lock jobs

Locks due jobs, which match the specified conditions.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
partition
string <date>

Partition condition.

id
integer <int32>

Job condition - must be used in combination with a partition.

bpmnElementIds
Array of strings <= 100 items unique

IDs of a BPMN elements to include.

elementInstanceId
integer <int32>

Element instance condition - must be used in combination with a partition.

processIds
Array of integers <int32> <= 100 items unique [ items <int32 > ]

IDs of processes to include.

processInstanceId
integer <int32>

Process instance condition - must be used in combination with a partition.

limit
integer <int32> [ 1 .. 1000 ]

Maximum number of jobs to lock.

workerId
required
string

ID of the worker that locks the jobs.

Responses

Request samples

Content type
application/json
{
  • "partition": "2025-05-01",
  • "processIds": [
    ],
  • "limit": 1,
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/json
{
  • "count": 1,
  • "jobs": [
    ]
}

Query jobs

Performs a job query.

Authorizations:
ApiKeyAuth
query Parameters
offset
integer <int32>

The number of results to skip, before returning any result. If offset is 0, no results are skipped.

limit
integer <int32>

Maximum number of results to return. If limit is 0, all results are returned.

Request Body schema: application/json
partition
string <date>

Partition filter.

id
integer <int32>

Job filter.

elementInstanceId
integer <int32>

Element instance filter.

processId
integer <int32>

Process filter.

processInstanceId
integer <int32>

Process instance filter.

Responses

Request samples

Content type
application/json
{
  • "partition": "2025-04-11",
  • "processInstanceId": 576
}

Response samples

Content type
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Unlock jobs

Unlocks locked, but uncompleted, jobs that are currently locked by a specific worker.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
partition
string <date>

Partition condition.

id
integer <int32>

Job condition - must be used in combination with a partition.

workerId
required
string

Condition that restricts the jobs, to be locked by a specific worker.

Responses

Request samples

Content type
application/json
{
  • "partition": "2025-05-01",
  • "workerId": "default-worker"
}

Response samples

Content type
application/json
{
  • "count": 1
}

Complete job

Completes a locked job.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

Request Body schema: application/json
object (JobCompletion)

JobCompletion is used to complete jobs of various types.

required
object

Variables to set or delete at element instance scope.

error
string

Optional error, used to fail a job due to a technical problem.

required
object

Variables to set or delete at process instance scope.

retryCount
integer <int32> >= 0

Number of retries left. If > 0, a retry job is created. Otherwise, an incident is created.

retryTimer
string

Duration until a retry job becomes due. At this point in time a retry job can be locked by a worker.

workerId
required
string

ID of the worker that locked and completed the job.

Responses

Request samples

Content type
application/json
Example
{
  • "processVariables": {
    },
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/json
{
  • "partition": "2025-05-01",
  • "id": 1042,
  • "elementId": 8,
  • "elementInstanceId": 2298,
  • "processId": 2,
  • "processInstanceId": 576,
  • "bpmnElementId": "serviceTaskA",
  • "completedAt": "2025-05-01T18:17:08.044Z",
  • "createdAt": "2025-05-01T17:44:19.997Z",
  • "createdBy": "go-bpmn",
  • "dueAt": "2025-05-01T17:44:19.997Z",
  • "lockedAt": "2025-05-01T17:59:30.657Z",
  • "lockedBy": "go-bpmn",
  • "retryCount": 0,
  • "type": "EXECUTE"
}

Processes

A process represents a BPMN process that consists of a set of BPMN elements.

Create process

Creates a process that is modeled as BPMN XML.

If a process with the same BPMN process ID and version exists, the BPMN XML is compared. When the BPMN XML equals, the existing process is returned. When the BPMN XML differs, a problem of type CONFLICT is returned.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
bpmnProcessId
required
string

ID of the process element within the BPMN XML.

bpmnXml
required
string

Model of the BPMN process as XML.

parallelism
integer <int32> >= 0

Maximum number of parallel process instances being executed. If 0, the number of parallel process instances is unlimited.

required
object

Optional tags, consisting of name and value pairs.

version
required
string

Arbitrary process version.

workerId
required
string

ID of the worker that created the process.

Responses

Request samples

Content type
application/json
{
  • "bpmnProcessId": "parallelServiceTasksTest",
  • "bpmnXml": "<...>",
  • "parallelism": 5,
  • "tags": {
    },
  • "version": "1",
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "bpmnProcessId": "parallelServiceTasksTest",
  • "createdAt": "2025-05-01T17:43:34.956Z",
  • "createdBy": "go-bpmn",
  • "parallelism": 5,
  • "tags": {
    },
  • "version": "1"
}

Query processes

Performs a process query.

Authorizations:
ApiKeyAuth
query Parameters
offset
integer <int32>

The number of results to skip, before returning any result. If offset is 0, no results are skipped.

limit
integer <int32>

Maximum number of results to return. If limit is 0, all results are returned.

Request Body schema: application/json
id
integer <int32>

Process filter.

object

Tags, a process must have, to be included.

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Get BPMN XML

Gets the BPMN XML of an existing process.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer <int32>

Entity ID.

Responses

Response samples

Content type
application/problem+json
{
  • "status": 404,
  • "type": "NOT_FOUND",
  • "title": "failed to get BPMN XML",
  • "detail": "process 7 could not be found"
}

Process instances

A process instance is an instance of a BPMN process.

Create process instance

Creates a process instance from an existing process.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
bpmnProcessId
required
string

BPMN ID of an existing process.

correlationKey
string

Optional key, used to correlate a process instance with a business entity.

required
object

Optional tags, consisting of name and value pairs.

required
object

Variables to set at process instance scope.

version
required
string

Version of an existing process.

workerId
required
string

ID of the worker that created the process instance.

Responses

Request samples

Content type
application/json
{
  • "bpmnProcessId": "parallelServiceTasksTest",
  • "correlationKey": "123456",
  • "tags": {
    },
  • "variables": {
    },
  • "version": "1",
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/json
{
  • "partition": "2025-04-11",
  • "id": 576,
  • "processId": 2,
  • "bpmnProcessId": "parallelServiceTasksTest",
  • "correlationKey": "123456",
  • "createdAt": "2025-05-01T17:44:19.997Z",
  • "createdBy": "go-bpmn",
  • "startedAt": "2025-05-01T17:44:19.997Z",
  • "state": "STARTED",
  • "stateChangedBy": "go-bpmn",
  • "tags": {
    },
  • "version": "1"
}

Query process instances

Performs a process instance query.

Authorizations:
ApiKeyAuth
query Parameters
offset
integer <int32>

The number of results to skip, before returning any result. If offset is 0, no results are skipped.

limit
integer <int32>

Maximum number of results to return. If limit is 0, all results are returned.

Request Body schema: application/json
partition
string <date>

Partition filter.

id
integer <int32>

Process instance filter.

processId
integer <int32>

Process filter.

object

Tags, a process instance must have, to be included.

Responses

Request samples

Content type
application/json
{
  • "partition": "2019-08-24",
  • "id": 0,
  • "processId": 0,
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Resume process instance

Resumes a suspended process instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

Request Body schema: application/json
workerId
required
string

ID of the worker that resumed the process instance.

Responses

Request samples

Content type
application/json
{
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/problem+json
{
  • "status": 404,
  • "type": "NOT_FOUND",
  • "title": "failed to resume process instance",
  • "detail": "process instance 2025-05-01/577 could not be found"
}

Suspend process instance

Suspends a started process instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

Request Body schema: application/json
workerId
required
string

ID of the worker that suspended the process instance.

Responses

Request samples

Content type
application/json
{
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/problem+json
{
  • "status": 404,
  • "type": "NOT_FOUND",
  • "title": "failed to suspend process instance",
  • "detail": "process instance 2025-05-01/577 could not be found"
}

Get process variables

Gets variables of an active or ended process instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

query Parameters
names
string
Examples: names=a,b,c

Comma separated list of variables to include.

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "variables": {
    }
}

Set process variables

Sets or deletes variables of an active process instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

Request Body schema: application/json
required
object

Variables to set or delete. For a variable deletion, no value must be provided.

workerId
required
string

ID of the worker that set the variables.

Responses

Request samples

Content type
application/json
Example
{
  • "variables": {
    },
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/problem+json
{
  • "status": 400,
  • "type": "VALIDATION",
  • "title": "invalid request body",
  • "detail": "failed to validate request body",
  • "errors": [
    ]
}

Tasks

A task is a unit of work, which must be locked, executed and completed by an engine.

Execute tasks

Locks and executes due tasks, which match the specified conditions.

Due tasks are normally handled by a task executor, running inside the engine. When waiting for a due task to be completed during testing, this operation must be called!

Authorizations:
ApiKeyAuth
Request Body schema: application/json
partition
string <date>

Partition condition.

id
integer <int32>

Task condition - must be used in combination with a partition.

elementInstanceId
integer <int32>

Element instance condition - must be used in combination with a partition.

processInstanceId
integer <int32>

Process instance condition - must be used in combination with a partition.

type
string (TaskType)
Enum: "DEQUEUE_PROCESS_INSTANCE" "JOIN_PARALLEL_GATEWAY" "START_PROCESS_INSTANCE" "CREATE_PARTITION" "DETACH_PARTITION" "DROP_PARTITION"

TaskType describes the different types of tasks, an engine needs to execute.

  • DEQUEUE_PROCESS_INSTANCE dequeues a queued process instance
  • JOIN_PARALLEL_GATEWAY continues a parallel gateway by joining executions
  • START_PROCESS_INSTANCE starts a queued process instance

Management related types, that are only relevant for a pg engine:

  • CREATE_PARTITION creates the table partitions for a specific date
  • DETACH_PARTITION detaches completed table partitions
  • DROP_PARTITION drops a detached table partitions
limit
integer <int32> [ 1 .. 100 ]

Maximum number of tasks to lock and execute.

Responses

Request samples

Content type
application/json
{
  • "partition": "2025-05-01",
  • "processInstanceId": 576,
  • "limit": 1
}

Response samples

Content type
application/json
{
  • "locked": 1,
  • "completed": 1,
  • "failed": 0,
  • "completedTasks": [
    ]
}

Query tasks

Performs a task query.

Authorizations:
ApiKeyAuth
query Parameters
offset
integer <int32>

The number of results to skip, before returning any result. If offset is 0, no results are skipped.

limit
integer <int32>

Maximum number of results to return. If limit is 0, all results are returned.

Request Body schema: application/json
partition
string <date>

Partition filter.

id
integer <int32>

Task filter.

elementInstanceId
integer <int32>

Element instance filter.

processId
integer <int32>

Process filter.

processInstanceId
integer <int32>

Process instance filter.

type
string (TaskType)
Enum: "DEQUEUE_PROCESS_INSTANCE" "JOIN_PARALLEL_GATEWAY" "START_PROCESS_INSTANCE" "CREATE_PARTITION" "DETACH_PARTITION" "DROP_PARTITION"

TaskType describes the different types of tasks, an engine needs to execute.

  • DEQUEUE_PROCESS_INSTANCE dequeues a queued process instance
  • JOIN_PARALLEL_GATEWAY continues a parallel gateway by joining executions
  • START_PROCESS_INSTANCE starts a queued process instance

Management related types, that are only relevant for a pg engine:

  • CREATE_PARTITION creates the table partitions for a specific date
  • DETACH_PARTITION detaches completed table partitions
  • DROP_PARTITION drops a detached table partitions

Responses

Request samples

Content type
application/json
{
  • "partition": "2019-08-24",
  • "id": 0,
  • "elementInstanceId": 0,
  • "processId": 0,
  • "processInstanceId": 0,
  • "type": "DEQUEUE_PROCESS_INSTANCE"
}

Response samples

Content type
application/json
{
  • "count": 3,
  • "results": [
    ]
}

Unlock tasks

Unlocks locked, but uncompleted, tasks that are currently locked by a specific engine.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
partition
string <date>

Partition condition.

id
integer <int32>

Task condition - must be used in combination with a partition.

engineId
required
string

Condition that restricts the tasks, to be locked by a specific engine.

Responses

Request samples

Content type
application/json
{
  • "partition": "2025-05-01",
  • "engineId": "default-engine"
}

Response samples

Content type
application/json
{
  • "count": 1
}

Variables

A variable is data, identified by a name, that exists in the scope of a process instance or element instance.

Get element variables

Gets variables of an active or ended element instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

query Parameters
names
string
Examples: names=a,b,c

Comma separated list of variables to include.

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "variables": {
    }
}

Set element variables

Sets or deletes variables of an active element instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

Request Body schema: application/json
required
object

Variables to set or delete. For a variable deletion, no value must be provided.

workerId
required
string

ID of the worker that set the variables.

Responses

Request samples

Content type
application/json
Example
{
  • "variables": {
    },
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/problem+json
{
  • "status": 400,
  • "type": "VALIDATION",
  • "title": "invalid request body",
  • "detail": "failed to validate request body",
  • "errors": [
    ]
}

Get process variables

Gets variables of an active or ended process instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

query Parameters
names
string
Examples: names=a,b,c

Comma separated list of variables to include.

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "variables": {
    }
}

Set process variables

Sets or deletes variables of an active process instance.

Authorizations:
ApiKeyAuth
path Parameters
partition
required
string <date>

Entity partition.

id
required
integer <int32>

Entity ID.

Request Body schema: application/json
required
object

Variables to set or delete. For a variable deletion, no value must be provided.

workerId
required
string

ID of the worker that set the variables.

Responses

Request samples

Content type
application/json
Example
{
  • "variables": {
    },
  • "workerId": "go-bpmn"
}

Response samples

Content type
application/problem+json
{
  • "status": 400,
  • "type": "VALIDATION",
  • "title": "invalid request body",
  • "detail": "failed to validate request body",
  • "errors": [
    ]
}

Query variables

Performs a variable query.

Authorizations:
ApiKeyAuth
query Parameters
offset
integer <int32>

The number of results to skip, before returning any result. If offset is 0, no results are skipped.

limit
integer <int32>

Maximum number of results to return. If limit is 0, all results are returned.

Request Body schema: application/json
partition
string <date>

Partition filter.

elementInstanceId
integer <int32>

Element instance filter.

processInstanceId
integer <int32>

Process instance filter.

names
Array of strings

Names of variables to include.

Responses

Request samples

Content type
application/json
{
  • "partition": "2025-05-09",
  • "processInstanceId": 48,
  • "names": [
    ]
}

Response samples

Content type
application/json
{
  • "count": 1,
  • "results": [
    ]
}

Check readiness

Determines if the server is ready to accept requests.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
text/plain
ready

Set time

Increases the engine's time for testing purposes.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
time
required
string <date-time>

A future point in time.

Responses

Request samples

Content type
application/json
{
  • "time": "2025-05-10T00:00:00.000Z"
}

Response samples

Content type
application/problem+json
{
  • "status": "409,",
  • "type": "CONFLICT",
  • "title": "failed to set time",
  • "detail": "time 2025-05-08T17:43:56Z is before engine time 2025-05-09T19:19:21Z"
}