Execute Workflows

Trigger a workflow execution from your application. Workflows are built and published in the designer — the API is for starting them.

Base path: /process Auth: API Key (X-API-Key header) or JWT

There are two endpoints for starting a workflow execution. Both accept the same request body and query parameters and return the same response — the difference is in API key scope:

Endpoint	Use when
POST /process/exec	You have an org-scoped API key (the standard case — keys created in the UI belong to your organization)
POST /process/start	You have a system-level API key that can execute workflows across any organization

For most integrations, use /process/exec.

---

Start a Workflow

POST /process/exec

Triggers a workflow execution scoped to your organization. Returns immediately with an instance ID. The workflow runs asynchronously.

Query parameters:

Parameter	Type	Required	Description
environment	string	No	DEVELOPMENT or PRODUCTION. Defaults to PRODUCTION.
versionNumber	string	No	Specific version to run. Defaults to the active published version.

Request body:

{
  "processId": "your-flow-uuid",
  "correlationKey": "order-9981",
  "data": {
    "customerName": "Jane Smith",
    "issueType": "billing",
    "message": "I was charged twice"
  }
}

Field	Type	Required	Description
processId	string	Yes	The flow UUID — find it in the designer URL or flow settings
correlationKey	string	No	Your own reference key. Used to correlate catch events.
data	object	No	Input variables. Each key becomes available as {varName} in node properties.

Response: 200 OK

{
  "processInstanceId": "inst_xyz789",
  "processId": "your-flow-uuid",
  "status": "started",
  "startTime": "2026-02-20T10:00:00.123Z"
}

Use the processInstanceId to check execution status or resume a waiting task.

Example:

curl -X POST https://your-server/process/exec \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apk_YOUR_KEY_ID_YOUR_SECRET" \
  -d '{
    "processId": "your-flow-uuid",
    "data": { "orderId": "ORD-001", "amount": 149.99 }
  }'

---

Start a Workflow (System Key)

POST /process/start

Identical to /process/exec in request format and response — but intended for system-level API keys that are not scoped to a single organization. A system key can trigger any organization's published workflow; the execution is attributed to the organization that owns the flow.

Use this endpoint only if you hold a system-level key issued by the platform administrator. Regular org-scoped keys should use /process/exec.

---

Resume a User Task

POST /process/task

Submits a response for a flow that is paused at a User Task or Input Node, waiting for external input.

Auth: API Key or JWT · Permission: WORKFLOW_EXECUTE

Request body:

{
  "processInstanceId": "inst_xyz789",
  "nodeId": "approval-step",
  "action": "COMPLETE",
  "data": {
    "decision": "approved",
    "notes": "Looks good, proceed"
  }
}

Field	Type	Required	Description
processInstanceId	string	Yes	The paused execution to resume
nodeId	string	Yes	The node ID waiting for input (visible in the designer)
action	string	Yes	COMPLETE to proceed, CANCEL to abort the task
data	object	No	Form fields or decision values to pass back into the flow

Response: 200 OK

{
  "processInstanceId": "inst_xyz789",
  "status": "resumed"
}

The flow continues from the node that was waiting.

---

Find your processId

The processId is the UUID in the designer URL: /designer/3f8a1c2d-... — that's the value to use.