Using Workflows via REST API

All workflow operations are available at /api/workflow. Every request must be authenticated with a session cookie or Bearer token. The permission key required is workflow (130_001).

Base URL

https://workingagents.ai/api/workflow

All responses are JSON. All request bodies are JSON with Content-Type: application/json.

---

Create and Start a Workflow

POST /api/workflow

Body:

{
  "name": "my-workflow",
  "flow": {
    "start": {
      "name": "greet",
      "tool": "get_greeting",
      "args": {},
      "next": "count"
    },
    "count": {
      "name": "count",
      "tool": "get_counter",
      "args": {},
      "done": true
    }
  },
  "input": {}
}

Response:

{
  "id": 1773850841512,
  "status": "started"
}

The workflow starts immediately. The executor picks up the first step within one second.

With Input Variables

Step args can use {{input.key}} placeholders resolved from the input map:

curl -X POST https://workingagents.ai/api/workflow \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "knowledge-search",
    "flow": {
      "start": {
        "name": "search",
        "tool": "knowledge_search",
        "args": {"query": "{{input.topic}}"},
        "done": true
      }
    },
    "input": {"topic": "access control permissions"}
  }'

---

List Workflows

GET /api/workflow
GET /api/workflow?limit=10

Response:

[
  {
    "id": 1773850841512,
    "updated_at": 1773850841600,
    "name": "knowledge-search",
    "status": "completed",
    "created_by": "james",
    "completed_at": 1773850843000,
    "cancelled_at": null
  },
  {
    "id": 1773850800000,
    "name": "write-with-approval",
    "status": "running",
    ...
  }
]

Returns up to 50 workflows by default, newest first. Use ?limit=N to change.

---

Get a Workflow with Steps

GET /api/workflow/:id

curl https://workingagents.ai/api/workflow/1773850841512 \
  -H "Authorization: Bearer <token>"

Response:

{
  "id": 1773850841512,
  "name": "knowledge-search",
  "status": "completed",
  "created_by": "james",
  "steps": [
    {
      "id": 1773850841600,
      "name": "search",
      "tool": "knowledge_search",
      "status": "done",
      "attempt": 1,
      "result_json": "[{\"title\":\"Access Control\",\"score\":0.92}]",
      "started_at": 1773850841700,
      "completed_at": 1773850842500
    }
  ]
}

The result_json field contains the JSON-encoded output of the tool call.

---

Cancel a Workflow

DELETE /api/workflow/:id

curl -X DELETE https://workingagents.ai/api/workflow/1773850841512 \
  -H "Authorization: Bearer <token>"

Response:

{"cancelled": true}

---

Unblock a Pending Step (Approval Gate)

When a step has "tool": null, the executor creates it and waits. Use this endpoint to release it:

POST /api/workflow/:step_id/ready

curl -X POST https://workingagents.ai/api/workflow/1773850841700/ready \
  -H "Authorization: Bearer <token>"

Response:

{"queued": true}

The executor picks up the step on the next poll (within one second) and continues the workflow.

---

Full Example: Approval-Gated Write

Step 1 – create the workflow:

curl -X POST https://workingagents.ai/api/workflow \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "write-with-approval",
    "flow": {
      "start": {
        "name": "await_approval",
        "tool": null,
        "args": {},
        "next": "do_write"
      },
      "do_write": {
        "name": "do_write",
        "tool": "knowledge_add",
        "args": {
          "title": "{{input.title}}",
          "content": "{{input.content}}",
          "scope": "general"
        },
        "done": true
      }
    },
    "input": {
      "title": "New Policy",
      "content": "All agents must request approval before writing."
    }
  }'
# => {"id": 1773850841512, "status": "started"}

Step 2 – check status, find the pending step:

curl https://workingagents.ai/api/workflow/1773850841512 \
  -H "Authorization: Bearer <token>"
# => steps[0].id = 1773850841600, status = "running" (awaiting external ready signal)

Step 3 – approve:

curl -X POST https://workingagents.ai/api/workflow/1773850841600/ready \
  -H "Authorization: Bearer <token>"
# => {"queued": true}

Step 4 – verify completion:

curl https://workingagents.ai/api/workflow/1773850841512 \
  -H "Authorization: Bearer <token>"
# => status: "completed", steps[1].status: "done"

---

Branching Example

curl -X POST https://workingagents.ai/api/workflow \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "branch-demo",
    "flow": {
      "start": {
        "name": "check",
        "tool": "is_admin",
        "args": {},
        "branch": [
          {"if": "result == true",  "then": "admin_path"},
          {"if": "result == false", "then": "user_path"}
        ]
      },
      "admin_path": {
        "name": "admin_path",
        "tool": "get_greeting",
        "args": {"name": "World"},
        "done": true
      },
      "user_path": {
        "name": "user_path",
        "tool": "get_counter",
        "args": {},
        "done": true
      }
    },
    "input": {}
  }'

---

Error Responses

Status	Meaning
400	Missing required field (name)
403	No workflow permission
404	Workflow not found
422	Flow validation error (e.g. missing start key)

{"error": "Flow must have a 'start' key"}