Workflows

Workflow routes are the heart of the control-plane API.

A workflow is the top-level run record that ties together the playbook, workspace, work items, tasks, activations, artifacts, and operator history for one piece of work.

Main Route Families

POST /api/v1/workflows
GET /api/v1/workflows
GET /api/v1/workflows/:id
POST /api/v1/workflows/:id/redrives
GET /api/v1/workflows/:id/events
GET /api/v1/workflows/:id/board
GET /api/v1/workflows/:id/stages
POST /api/v1/workflows/:id/activations
GET /api/v1/operations/workflows/...

Create Workflow

POST /api/v1/workflows

Scope: admin

Request body

{
  "request_id": "launch-001",
  "playbook_id": "11111111-1111-1111-1111-111111111111",
  "workspace_id": "22222222-2222-2222-2222-222222222222",
  "name": "Release readiness review",
  "operator_note": "Focus on migration and deployment risk.",
  "parameters": {
    "target_branch": "main"
  },
  "metadata": {
    "source": "release-pipeline"
  },
  "budget": {
    "token_budget": 40000,
    "cost_cap_usd": 12,
    "max_duration_minutes": 45
  },
  "live_visibility_mode": "enhanced",
  "initial_input_packet": {
    "summary": "Review open release blockers and propose next actions.",
    "structured_inputs": {
      "release_version": "0.1.0"
    },
    "files": [
      {
        "file_name": "release-context.md",
        "content_base64": "IyBSZWxlYXNlIGNvbnRleHQK",
        "content_type": "text/markdown"
      }
    ]
  }
}

Required fields

playbook_id
workspace_id
name

Request fields

Field	Required	Contract	Meaning
`request_id`	No	`string`	Caller-supplied idempotency key for launch retries. Reuse it only when retrying the same workflow creation request.
`playbook_id`	Yes	`UUID`	Which playbook definition should govern the run.
`workspace_id`	Yes	`UUID`	Which workspace provides durable repository and memory context.
`name`	Yes	`string`	Human-friendly run title shown in the dashboard and operator surfaces.
`operator_note`	No	`string`	Short operator-authored steering note attached to the launch.
`parameters`	No	`string map`	String-keyed playbook input values that the workflow can read as launch parameters.
`metadata`	No	`arbitrary JSON object`	Free-form annotations for integrations, correlation, or operator context.
`budget`	No	`structured object`	Execution budget constraints such as token, cost, and max duration caps.
`live_visibility_mode`	No	`enum`	Controls how much live operator-facing execution detail the platform should surface for this workflow.
`initial_input_packet`	No	`structured object`	Structured kickoff material attached at launch time. Use it for summaries, files, and other initial operator-provided context.

`initial_input_packet` fields

Field	Contract	Meaning
`summary`	`string`	Human-readable kickoff brief that becomes part of the initial workflow context.
`structured_inputs`	`arbitrary JSON object`	Machine-readable launch data that downstream orchestration and specialists can inspect.
`files`	`structured object[]`	Operator-supplied files that should travel with the initial packet.

Response

{
  "data": {
    "id": "33333333-3333-3333-3333-333333333333",
    "workspace_id": "22222222-2222-2222-2222-222222222222",
    "playbook_id": "11111111-1111-1111-1111-111111111111",
    "name": "Release readiness review",
    "state": "pending",
    "lifecycle": "planned",
    "parameters": {
      "target_branch": "main"
    },
    "token_budget": 40000,
    "cost_cap_usd": 12,
    "max_duration_minutes": 45,
    "metadata": {
      "source": "release-pipeline"
    },
    "attempt_number": 1,
    "attempt_kind": "initial",
    "created_at": "2026-03-31T18:55:00.000Z",
    "updated_at": "2026-03-31T18:55:00.000Z"
  }
}

Response fields

Field	Contract	Meaning
`id`	`server-generated`	Canonical workflow identifier.
`workspace_id` / `playbook_id`	`UUID`	The durable workspace and playbook chosen at creation time.
`state`	`enum`	Current workflow state, such as `pending`, `in_progress`, or `completed`.
`lifecycle`	`enum`	Higher-level lifecycle classification for the workflow run.
`parameters`	`string map`	Sanitized launch parameters persisted on the workflow record.
`token_budget` / `cost_cap_usd` / `max_duration_minutes`	`numeric scalar`	Flattened budget values after creation.
`metadata`	`arbitrary JSON object`	Sanitized workflow metadata.
`attempt_number`	`server-generated`	Which attempt this workflow instance represents within its overall lineage.
`attempt_kind`	`enum-like string`	Whether this is the original run or a later retry/redrive.

List Workflows

GET /api/v1/workflows

Scope: agent

Query parameters

workspace_id
playbook_id
state
page
per_page

Response shape

{
  "data": [
    {
      "id": "33333333-3333-3333-3333-333333333333",
      "workspace_id": "22222222-2222-2222-2222-222222222222",
      "playbook_id": "11111111-1111-1111-1111-111111111111",
      "name": "Release readiness review",
      "state": "in_progress",
      "lifecycle": "planned",
      "workspace_name": "Platform",
      "playbook_name": "Release Review",
      "task_counts": {
        "pending": 1,
        "in_progress": 2,
        "completed": 4
      },
      "work_item_summary": {
        "total_work_items": 5,
        "open_work_item_count": 2,
        "blocked_work_item_count": 1,
        "completed_work_item_count": 3,
        "active_stage_count": 1,
        "awaiting_gate_count": 0,
        "active_stage_names": [
          "Review"
        ]
      },
      "created_at": "2026-03-31T18:55:00.000Z",
      "updated_at": "2026-03-31T19:10:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "pages": 1
  }
}

The list response is intentionally a board-friendly summary, not the full deep workflow packet.

List response fields

Field	Contract	Meaning
`workspace_name` / `playbook_name`	`server-generated`	Resolved display names used by list and board views.
`task_counts`	`structured object`	Shallow count rollup by task state for fast list rendering. The keys are task-state names.
`work_item_summary.total_work_items`	`server-generated`	Total work items currently attached to the workflow.
`work_item_summary.open_work_item_count`	`server-generated`	Work items not yet closed.
`work_item_summary.blocked_work_item_count`	`server-generated`	Work items blocked on something external or unresolved.
`work_item_summary.completed_work_item_count`	`server-generated`	Work items already finished.
`work_item_summary.active_stage_count`	`server-generated`	Number of currently active stages.
`work_item_summary.awaiting_gate_count`	`server-generated`	How many approval or gate checkpoints are currently waiting.
`work_item_summary.active_stage_names`	`server-generated string[]`	Ordered list of currently active stage names.

Get Workflow

GET /api/v1/workflows/:id

Scope: agent

Response shape

The detail payload extends the core workflow record with attached task, activation, and work-item state.

{
  "data": {
    "id": "33333333-3333-3333-3333-333333333333",
    "workspace_id": "22222222-2222-2222-2222-222222222222",
    "playbook_id": "11111111-1111-1111-1111-111111111111",
    "name": "Release readiness review",
    "state": "in_progress",
    "lifecycle": "planned",
    "parameters": {
      "target_branch": "main"
    },
    "metadata": {},
    "tasks": [
      {
        "id": "44444444-4444-4444-4444-444444444444",
        "title": "Review deploy blockers",
        "state": "in_progress"
      }
    ],
    "work_items": [
      {
        "id": "55555555-5555-5555-5555-555555555555",
        "title": "Assess release risk",
        "stage_name": "Review"
      }
    ],
    "activations": [
      {
        "id": "66666666-6666-6666-6666-666666666666",
        "status": "queued"
      }
    ],
    "workflow_stages": [
      {
        "name": "Review",
        "status": "active"
      }
    ],
    "created_at": "2026-03-31T18:55:00.000Z",
    "updated_at": "2026-03-31T19:10:00.000Z"
  }
}

Detail-only fields

Field	Contract	Meaning
`tasks`	`task record[]`	Attached task records for the workflow. This is a flat workflow-level list, not tasks nested under each work item. Link them with `task.work_item_id`.
`work_items`	`work item record[]`	Structured work planning units inside the workflow.
`activations`	`activation record[]`	Orchestration dispatch cycles and wake-ups for the workflow.
`workflow_stages`	`stage projection[]`	Current stage projections used by platform and dashboard views.

Redrive Workflow

POST /api/v1/workflows/:id/redrives

Scope: admin

Request body

{
  "request_id": "redrive-001",
  "reason": "Original run used the wrong model route.",
  "summary": "Re-run with corrected model settings.",
  "inheritance_policy": "inherit_all",
  "live_visibility_mode": "standard",
  "parameters": {
    "target_branch": "main"
  }
}

Redrive fields

Field	Contract	Meaning
`request_id`	`string`	Optional idempotency key for the redrive request itself.
`name`	`string`	Optional override name for the new run.
`reason`	`string`	Short explanation of why the workflow is being redriven.
`summary`	`string`	Operator-facing summary of the redrive intent.
`steering_instruction`	`string`	Extra guidance for the new run beyond the original launch note.
`redrive_input_packet_id`	`UUID`	Optional previously recorded input packet to reuse as the new starting packet.
`inheritance_policy`	`enum`	Whether to carry forward prior settings and context, or start fresh.
`parameters`	`string map`	Optional string launch-parameter overrides.
`structured_inputs`	`arbitrary JSON object`	Optional structured input overrides for the new attempt.
`files`	`structured object[]`	Optional operator-supplied files for the new attempt.
`live_visibility_mode`	`enum`	Per-redrive override for workflow live visibility.

Response

{
  "data": {
    "id": "77777777-7777-7777-7777-777777777777",
    "applied": true
  }
}

Workflow Events

GET /api/v1/workflows/:id/events

Scope: agent

Query parameters

types or event_type
entity_type
entity_id
work_item_id
stage_name
activation_id
gate_id
after
limit

Response

{
  "data": [
    {
      "id": 1234,
      "type": "task.state_changed",
      "entity_type": "task",
      "entity_id": "44444444-4444-4444-4444-444444444444",
      "created_at": "2026-03-31T19:10:00.000Z",
      "data": {
        "from_state": "claimed",
        "to_state": "in_progress"
      }
    }
  ],
  "meta": {
    "next_after": "1234"
  }
}

Activations

Enqueue activation

POST /api/v1/workflows/:id/activations

Scope: admin

Request body:

{
  "request_id": "activate-001",
  "reason": "Operator requested immediate re-evaluation.",
  "event_type": "operator.refresh_requested",
  "payload": {
    "source": "dashboard"
  }
}

Response:

{
  "data": {
    "id": "88888888-8888-8888-8888-888888888888",
    "applied": true
  }
}

List activations

GET /api/v1/workflows/:id/activations

Scope: agent

The list and detail routes expose activation packets for orchestration history and queue state.

Workflow Operations Surfaces

The operations/workflows family powers the live dashboard views and is useful when you want the same operational packets the dashboard consumes.

Rail view

GET /api/v1/operations/workflows/rail

Representative query fields:

mode: live, recent, or history
needs_action_only
lifecycle: all, ongoing, or planned
search
page
per_page
workflow_id

Workspace packet

GET /api/v1/operations/workflows/:id/workspace

Representative query fields:

work_item_id
task_id
tab_scope
live_console_after
live_console_limit
briefs_after
history_after
deliverables_after

Response packets in this family are intentionally richer than the plain workflow record because they power live console, brief, history, board, and deliverable views in one request.

Workflows

Main Route Families

Create Workflow

Request body

Required fields

Request fields

initial_input_packet fields

Response

Response fields

List Workflows

Query parameters

Response shape

List response fields

Get Workflow

Response shape

Detail-only fields

Redrive Workflow

Request body

Redrive fields

Response

Workflow Events

Query parameters

Response

Activations

Enqueue activation

List activations

Workflow Operations Surfaces

Rail view

Workspace packet

`initial_input_packet` fields