Skip to main content

Quickstart

Run your first process in under 5 minutes.

Prerequisites​

  • curl (or any HTTP client)

1. Register and Get an API Key​

Step 1 — Submit your registration:

Request:

curl -X POST https://api.stateway.io/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Company",
    "email": "you@mycompany.com"
  }'

Response:

{
  "data": {
    "tenantId": "a1b2c3d4-...",
    "status": "pending_verification",
    "message": "A 6-digit verification code has been sent to your email. It is valid for 10 minutes."
  }
}

Step 2 — Verify your email with the code you received:

Request:

curl -X POST https://api.stateway.io/v1/register/verify \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "a1b2c3d4-...",
    "verificationCode": "482910"
  }'

Response:

{
  "data": {
    "tenant": { "id": "a1b2c3d4-...", "name": "My Company", "plan": "free" },
    "apiKey": {
      "key": "sw_live_abc123...",
      "name": "Default API Key",
      "scopes": ["admin"]
    }
  }
}
tip

Save the key value — it is shown only once and you'll use it in every subsequent request.

2. Create a Process Definition​

Create a simple approval process in JSON format:

Request:

curl -X POST https://api.stateway.io/v1/definitions \
  -H "X-API-Key: sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "key": "expense-approval",
    "name": "Expense Approval",
    "source_type": "json",
    "source": {
      "key": "expense-approval",
      "elements": [
        { "id": "start",  "type": "startEvent", "outgoing": ["flow1"] },
        { "id": "review", "type": "userTask",   "name": "Review Expense", "outgoing": ["flow2"] },
        { "id": "end",    "type": "endEvent" }
      ],
      "flows": [
        { "id": "flow1", "sourceRef": "start",  "targetRef": "review" },
        { "id": "flow2", "sourceRef": "review", "targetRef": "end" }
      ]
    }
  }'

Response:

{
  "data": {
    "id": "def_01j...",
    "key": "expense-approval",
    "version": 1,
    "name": "Expense Approval",
    "source_type": "json",
    "is_active": true,
    "created_at": "2026-04-26T12:00:00.000Z"
  }
}

Alternatively, you can use BPMN 2.0 XML. To generate well-formed BPMN 2.0 XML from a plain-language description, use the bpmn-xml-generator Claude skill. Here is the same process as BPMN XML:

Request:

curl -X POST https://api.stateway.io/v1/definitions \
  -H "X-API-Key: sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "key": "expense-approval",
    "name": "Expense Approval",
    "source_type": "bpmn",
    "source": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\" xmlns:stateway=\"https://stateway.io/schema/bpmn/1.0\"><bpmn:process id=\"expense-approval\" isExecutable=\"true\"><bpmn:startEvent id=\"start\"><bpmn:outgoing>flow1</bpmn:outgoing></bpmn:startEvent><bpmn:userTask id=\"review\" name=\"Review Expense\"><bpmn:incoming>flow1</bpmn:incoming><bpmn:outgoing>flow2</bpmn:outgoing></bpmn:userTask><bpmn:endEvent id=\"end\"><bpmn:incoming>flow2</bpmn:incoming></bpmn:endEvent><bpmn:sequenceFlow id=\"flow1\" sourceRef=\"start\" targetRef=\"review\"/><bpmn:sequenceFlow id=\"flow2\" sourceRef=\"review\" targetRef=\"end\"/></bpmn:process></bpmn:definitions>"
  }'

Response:

{
  "data": {
    "id": "def_01j...",
    "key": "expense-approval",
    "version": 1,
    "name": "Expense Approval",
    "source_type": "bpmn",
    "is_active": true,
    "created_at": "2026-04-26T12:00:00.000Z"
  }
}

3. Start a Process Instance​

Request:

curl -X POST https://api.stateway.io/v1/instances \
  -H "X-API-Key: sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "definition_key": "expense-approval",
    "variables": {
      "amount": 250.00,
      "description": "Office supplies"
    }
  }'

Response:

{
  "data": {
    "id": "inst_01j...",
    "definition_key": "expense-approval",
    "status": "running",
    "variables": { "amount": 250, "description": "Office supplies" },
    "started_at": "2026-04-26T12:01:00.000Z"
  }
}

4. Complete the Human Task​

List pending tasks:

Request:

curl https://api.stateway.io/v1/tasks \
  -H "X-API-Key: sw_live_abc123..."

Response:

{
  "data": [
    {
      "id": "task_01j...",
      "name": "Review Expense",
      "status": "pending",
      "instance_id": "inst_01j...",
      "assignee": null,
      "created_at": "2026-04-26T12:01:05.000Z"
    }
  ]
}

Complete the task (use the id from the response above):

Request:

curl -X POST https://api.stateway.io/v1/tasks/{task_id}/complete \
  -H "X-API-Key: sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "approved": true } }'

Response:

{
  "data": {
    "id": "task_01j...",
    "status": "completed"
  }
}

5. List Instances​

Check all instances for the process:

Request:

curl "https://api.stateway.io/v1/instances?definition_key=expense-approval" \
  -H "X-API-Key: sw_live_abc123..."

Response:

{
  "data": [
    {
      "id": "inst_01j...",
      "definition_key": "expense-approval",
      "status": "completed",
      "variables": { "amount": 250, "description": "Office supplies", "approved": true },
      "started_at": "2026-04-26T12:01:00.000Z",
      "ended_at": "2026-04-26T12:02:00.000Z"
    }
  ]
}

6. Check Instance Status​

Request:

curl https://api.stateway.io/v1/instances/{instance_id} \
  -H "X-API-Key: sw_live_abc123..."

Response:

{
  "data": {
    "id": "inst_01j...",
    "status": "completed",
    "variables": { "amount": 250, "description": "Office supplies", "approved": true },
    "ended_at": "2026-04-26T12:02:00.000Z"
  }
}

Next Steps​