Process API

Process API

The Process API provides access to process definitions, versions, instance counts, state filters, and BPMN diagrams.

Base Path: /process

License: Requires a valid enterprise license (HTTP 403 otherwise).

Endpoints

GET /process

Returns process definitions visible to ins7ght in the optional date range.

Query parameters:

Parameter Required Description
startDate No ISO 8601 — lower bound for instance activity filtering
endDate No ISO 8601 — upper bound

Example HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "invoice-process:1:abc123",
    "name": "Invoice Process",
    "key": "invoice-process",
    "instanceCount": "42",
    "version": 1,
    "latestVersion": 2
  }
]
Field Type Description
id string Process definition id from the engine
name string Process name
key string Process definition key
instanceCount string Display / count information from the provider
version integer Definition version
latestVersion integer Latest version hint from the provider

GET /process/{processKey}/version

Returns all Process objects (metadata per deployment/version) for the given processKey, optionally filtered by the same date range as GET /process.

Path parameters:

Parameter Required Description
processKey Yes Process definition key (must not be blank)

Query parameters: startDate, endDate (optional, same semantics as GET /process).

Example HTTP response: Same Process object shape as GET /process (one array entry per definition version for that key).

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "invoice-process:1:abc123",
    "name": "Invoice Process",
    "key": "invoice-process",
    "instanceCount": "12",
    "version": 1,
    "latestVersion": 2
  }
]

GET /process/states

Returns distinct process instance states observed for a process definition version (e.g. for building filters in the UI).

Query parameters:

Parameter Required Description
processKey Yes Process definition key
version Yes Process version
startDate No ISO 8601
endDate No ISO 8601

Example HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

["ACTIVE", "COMPLETED", "INTERNALLY_TERMINATED"]

Example when no deployment matches: HTTP 200 with body [].

GET /process/bpmn

Returns the BPMN 2.0 XML for a specific process version (binary body).

Query parameters:

Parameter Required Description
processKey Yes Process definition key
version Yes Process version

Response type: application/octet-stream (raw BPMN XML bytes; often the first bytes are <?xml).

Example HTTP response (BPMN fragment):

HTTP/1.1 200 OK
Content-Type: application/octet-stream

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" ...>
  ...
</bpmn:definitions>

Usage Examples

Get All Processes

curl -X GET "http://localhost:8899/process"

Get Versions for a Process

curl -X GET "http://localhost:8899/process/invoice-process/version"

List States for a Version

curl -G "http://localhost:8899/process/states" \
  --data-urlencode "processKey=invoice-process" \
  --data-urlencode "version=1"

Download BPMN Diagram

curl -X GET "http://localhost:8899/process/bpmn?processKey=invoice-process&version=1" -o invoice-process.bpmn

Calls that return data use HTTP 200 with the bodies shown in the example HTTP response sections above (application/json except BPMN, which is application/octet-stream XML).

Notes

  • The list returned by GET /process can include multiple entries per key (one row per definition version).
  • BPMN content is raw XML.
  • An empty or blank processKey on the version or states routes produces an error.

On this Page: