24. REST API

Workingflow exposes a JSON REST API for programmatic interaction with workflows. External systems (ERP, CI/CD, monitoring tools) can use these endpoints to discover processes, start instances, poll status, and download files.

Authentication

All API requests require a valid API key in the Authorization header:

Authorization: Bearer wf_your_api_key_here

Keys are managed via the admin UI at /admin/api-keys.

Endpoints

Note: Processes with start forms cannot be started via API — they require user interaction through the web UI. The list endpoint includes a hasStartForm field so callers can identify API-startable processes.

Full Example — Expense Reimbursement Demo

The following examples use the expense_reimbursement_demo process (no start form) that ships with the platform.

1. List Processes

GET /processapi/list
Authorization: Bearer wf_abc123def456...

Response:

[
  {
    "key": "expense_reimbursement_demo",
    "name": "Expense Reimbursement Demo",
    "version": 1,
    "description": "Demonstrates gateway loops (revise/resubmit) and SLA task escalation.",
    "hasStartForm": false
  },
  {
    "key": "leave_request_demo",
    "name": "Leave Request Demo",
    "version": 1,
    "description": "Employee leave request with manager approval, revision loop, HR acknowledgment, and SLA escalation.",
    "hasStartForm": true
  }
]

2. Start Process

POST /processapi/expense_reimbursement_demo/start
Authorization: Bearer wf_abc123def456...
Content-Type: application/json

{
  "variables": {
    "department": "Engineering",
    "notes": "Q2 travel expenses"
  }
}

Response (201 Created):

{
  "processInstanceId": "52407",
  "processDefinitionKey": "expense_reimbursement_demo",
  "message": "Process started successfully"
}

Attempting to start a process with a start form returns 422:

{
  "error": "Processes with start forms cannot be started via API: leave_request_demo",
  "code": "START_FORM_NOT_SUPPORTED"
}

3. Poll Status

GET /processapi/52407/status
Authorization: Bearer wf_abc123def456...

Response:

{
  "processInstanceId": "52407",
  "processDefinitionName": "Expense Reimbursement Demo",
  "processDefinitionKey": "expense_reimbursement_demo",
  "startTime": "2026-05-01T09:15:22.000+00:00",
  "endTime": null,
  "status": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "52412",
      "taskName": "Submit Expense Report",
      "assignee": null,
      "createTime": "2026-05-01T09:15:22.000+00:00"
    }
  ],
  "variables": {
    "department": "Engineering",
    "notes": "Q2 travel expenses",
    "initiator": "api:ERP Integration"
  },
  "files": []
}

4. Download File

GET /processapi/52407/files/a3f8b2c1_receipt.pdf
Authorization: Bearer wf_abc123def456...

Response: binary file download with Content-Disposition: attachment; filename="receipt.pdf".

Error Responses

All errors return consistent JSON: {"error": "message", "code": "ERROR_CODE"}