Workflow API

Trigger Workflows and query runs.

List Workflows

GET /v1/workflows?workspace_id=ws-001

Trigger Run (synchronous)

POST /v1/workflows/{id}/runs

{
  "inputs": {
    "topic": "Common pitfalls of RAG in enterprise",
    "tone": "deep technical",
    "length": 1500
  },
  "user_id": "u-001"
}

Response:

{
  "request_id": "req-xxx",
  "run_id": "run-abc",
  "workflow_id": "wf-001",
  "status": "completed",
  "duration_ms": 3200,
  "outputs": {
    "article": "..."
  },
  "usage": { "tokens_in": 1020, "tokens_out": 2080, "credits": 0.052 }
}

Long Workflows: use async

If a Workflow typically runs > 30s, use async trigger + Webhook notification.

Trigger Run (asynchronous)

POST /v1/workflows/{id}/runs?async=true

Returns immediately:

{
  "run_id": "run-abc",
  "status": "running"
}

Receive completion via Webhook or poll:

GET /v1/runs/{run_id}

List Runs

GET /v1/workflows/{id}/runs?status=failed&limit=20

Cancel a Run

POST /v1/runs/{run_id}/cancel

Only running runs can be cancelled.

Streaming Run Progress

POST /v1/workflows/{id}/runs
Accept: text/event-stream

Events:

event: node_start
data: {"node": "Generate Outline", "started_at": "..."}

event: node_end
data: {"node": "Generate Outline", "duration_ms": 1400, "output": {...}}

event: usage
data: {...}

event: done
data: {"status": "completed", "outputs": {...}}

API · Workflow