Tasks

Task routes are where platform workflow meaning becomes executable work.

The workflow API tells you what run exists. The task API tells an agent or worker what specific unit of work to claim, execute, and settle.

Main Route Families

• POST /api/v1/tasks
• GET /api/v1/tasks
• GET /api/v1/tasks/:id
• GET /api/v1/tasks/:id/context
• GET /api/v1/tasks/:id/git
• POST /api/v1/tasks/claim
• POST /api/v1/tasks/:id/claim-credentials
• POST /api/v1/tasks/:id/start
• POST /api/v1/tasks/:id/complete
• POST /api/v1/tasks/:id/fail
• POST /api/v1/tasks/:id/retry

Create Task

POST /api/v1/tasks

Scope: agent

Request body

{
  "title": "Review deployment blockers",
  "type": "analysis",
  "task_kind": "delivery",
  "description": "Inspect recent release issues and summarize blockers.",
  "priority": "high",
  "workflow_id": "33333333-3333-3333-3333-333333333333",
  "work_item_id": "55555555-5555-5555-5555-555555555555",
  "workspace_id": "22222222-2222-2222-2222-222222222222",
  "stage_name": "Review",
  "request_id": "task-001",
  "role": "reviewer",
  "input": {
    "focus": "release blockers"
  },
  "context": {
    "source": "operator"
  },
  "timeout_minutes": 30,
  "token_budget": 12000,
  "cost_cap_usd": 4.5,
  "max_iterations": 12,
  "metadata": {
    "source": "api"
  }
}

Required fields

• title
• type

Request fields

Field	Required	Contract	Meaning
title	Yes	string	Human-readable task name.
type	Yes	enum	Broad task category such as analysis, code, or docs.
task_kind	No	enum	Higher-level control-plane classification such as delivery, assessment, approval, or orchestrator work.
description	No	string	Main execution prompt or task brief.
priority	No	enum	Scheduler hint used for queueing and operator displays.
workflow_id	No	UUID	Attach the task to an existing workflow.
work_item_id	No	UUID	Attach the task to a specific work item inside the workflow.
workspace_id	No	UUID	Override or pin the workspace context when the task is not inferred elsewhere.
stage_name	No	string	Stage label the task belongs to for workflow views and filtering.
request_id	No	string	Idempotency key for this task-creation request. Reuse it only when retrying the same create call.
role	No	string	Preferred specialist role name for the task.
input	No	arbitrary JSON object	Main structured payload the assignee is expected to work from.
context	No	arbitrary JSON object	Broader supporting packet that travels with the task.
execution_backend	No	enum	runtime_only means execution stays entirely in the runtime loop, while runtime_plus_task means the task also has task-level execution semantics recorded in the platform.
timeout_minutes, token_budget, cost_cap_usd	No	numeric scalar	Execution caps and cost guards.
max_iterations, llm_max_retries, auto_retry, max_retries	No	numeric or boolean scalar	Loop and retry controls for runtime execution.
metadata	No	arbitrary JSON object	Free-form annotations and caller context.

Response

{
  "data": {
    "id": "44444444-4444-4444-4444-444444444444",
    "title": "Review deployment blockers",
    "state": "pending",
    "workflow_id": "33333333-3333-3333-3333-333333333333",
    "work_item_id": "55555555-5555-5555-5555-555555555555",
    "workspace_id": "22222222-2222-2222-2222-222222222222",
    "stage_name": "Review",
    "role": "reviewer",
    "execution_backend": "runtime_plus_task",
    "used_task_sandbox": false,
    "created_at": "2026-03-31T18:55:00.000Z",
    "updated_at": "2026-03-31T18:55:00.000Z"
  }
}

Response fields

Field	Contract	Meaning
state	enum	Current execution state of the task.
execution_backend	enum	Backend contract the platform expects this task to follow.
used_task_sandbox	server-generated	Whether the task is currently or recently associated with a dedicated task sandbox/container rather than only a shared runtime loop.
role	string or null	Assigned role or preferred specialist profile for execution.

List And Fetch Tasks

List

GET /api/v1/tasks

Scope: agent

Query parameters include:

• state
• workspace_id
• workflow_id
• work_item_id
• assigned_agent_id
• activation_id
• execution_backend
• is_orchestrator_task
• page
• per_page

Response shape

{
  "data": [
    {
      "id": "44444444-4444-4444-4444-444444444444",
      "title": "Review deployment blockers",
      "state": "in_progress",
      "workflow_id": "33333333-3333-3333-3333-333333333333",
      "work_item_id": "55555555-5555-5555-5555-555555555555",
      "assigned_agent_id": "99999999-9999-9999-9999-999999999999",
      "assigned_worker_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "execution_backend": "runtime_plus_task",
      "execution_environment": {
        "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "name": "Default Runtime Image"
      },
      "used_task_sandbox": true
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "pages": 1
  }
}

Get

GET /api/v1/tasks/:id

Scope: agent or admin

The single-task route returns the sanitized task read model, including the latest structured handoff when one exists.

Common read-model fields

Field	Contract	Meaning
assigned_agent_id / assigned_worker_id	UUID or null	Current assignee pair when the task is claimed.
input	arbitrary JSON object or value	Sanitized execution payload.
context	arbitrary JSON object or value	Sanitized surrounding context packet.
output	arbitrary JSON object or value	Structured completion payload when the task has been settled.
error	structured object or null	Failure packet when the task was failed instead of completed.
metrics	arbitrary JSON object or null	Execution metrics reported by the runtime or worker.
git_info	arbitrary JSON object or null	Git-oriented evidence captured during execution.
verification	arbitrary JSON object or null	Verification payload recorded with completion. The platform only gives special meaning to documented keys such as passed.

Claim Task

POST /api/v1/tasks/claim

Scope: agent

Request body

{
  "agent_id": "99999999-9999-9999-9999-999999999999",
  "worker_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "routing_tags": [
    "reviewer",
    "typescript"
  ],
  "workflow_id": "33333333-3333-3333-3333-333333333333",
  "include_context": true
}

Success response

{
  "data": {
    "id": "44444444-4444-4444-4444-444444444444",
    "title": "Review deployment blockers",
    "state": "claimed",
    "input": {
      "focus": "release blockers"
    },
    "context": {
      "workflow": {},
      "workspace": {}
    }
  }
}

Claim request fields

Field	Contract	Meaning
agent_id	UUID	Which agent identity is attempting the claim.
worker_id	UUID	Optional backing worker execution claiming on behalf of the agent.
routing_tags	string[]	Queue filter tags. Only tasks compatible with these tags are eligible.
workflow_id	UUID	Restrict claims to a single workflow.
include_context	boolean	When true, return the richer context packet directly in the claim response.

No work response

204 No Content

That is normal when the queue has nothing claimable for the supplied agent and routing tags.

Claim Credentials

POST /api/v1/tasks/:id/claim-credentials

Scope: agent

Request body

{
  "llm_api_key_claim_handle": "claim://llm-key/123",
  "mcp_claim_handles": [
    "claim://mcp/alpha"
  ]
}

At least one claim handle is required. The platform resolves the credential handles into the concrete secret material the runtime needs.

Credential handle fields

Field	Contract	Meaning
llm_api_key_claim_handle	opaque	Handle for resolving the LLM provider API key assigned to the task.
llm_extra_headers_claim_handle	opaque	Handle for any extra LLM provider headers required by the task.
mcp_claim_handles	opaque[]	Handles for secret-bearing MCP server credentials the runtime needs to connect tools.

Task Context And Git Activity

Context

GET /api/v1/tasks/:id/context

Scope: agent

Optional query:

• agent_id

Representative response:

{
  "data": {
    "task": {
      "id": "44444444-4444-4444-4444-444444444444"
    },
    "workflow": {},
    "workspace": {},
    "documents": [],
    "attachments": []
  }
}

Git activity

GET /api/v1/tasks/:id/git

Scope: agent

Representative response:

{
  "data": {
    "linked_prs": [],
    "branches": [],
    "ci_status": null,
    "merge_history": [],
    "raw": {}
  }
}

Lifecycle Mutations

These routes drive task execution and review state:

• POST /api/v1/tasks/:id/start
• POST /api/v1/tasks/:id/complete
• POST /api/v1/tasks/:id/fail
• POST /api/v1/tasks/:id/retry
• POST /api/v1/tasks/:id/request-changes
• POST /api/v1/tasks/:id/reassign
• POST /api/v1/tasks/:id/skip
• POST /api/v1/tasks/:id/escalate

Complete task request

{
  "request_id": "complete-001",
  "output": {
    "summary": "Release blockers reviewed."
  },
  "metrics": {
    "tokens_in": 1200,
    "tokens_out": 500
  },
  "git_info": {
    "branches": [
      "release-review"
    ]
  },
  "verification": {
    "passed": true,
    "summary": "All requested checks passed."
  },
  "agent_id": "99999999-9999-9999-9999-999999999999",
  "worker_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}

Completion fields

Field	Contract	Meaning
request_id	string	Optional idempotency key for this completion write.
output	arbitrary JSON object or value	Canonical structured task result payload.
metrics	arbitrary JSON object	Runtime-reported usage and execution counters.
git_info	arbitrary JSON object	Branch, diff, or PR evidence associated with the work.
verification	arbitrary JSON object	Verification evidence such as test status, checks, or contract validation output. The platform currently interprets verification.passed as the canonical pass/fail flag if you supply one.
agent_id / worker_id	UUID	Execution identities settling the task.

Fail task request

{
  "request_id": "fail-001",
  "error": {
    "category": "infrastructure",
    "message": "Dependency install failed",
    "recoverable": true
  }
}

Failure fields

Field	Contract	Meaning
error.category	string	Broad error bucket such as infrastructure or validation.
error.message	string	Human-readable failure summary.
error.recoverable	boolean	Whether the caller believes the task can be retried or rerouted.

These mutation routes return the updated task in a { "data": ... } envelope.

Streaming

GET /api/v1/tasks/:id/stream

This route is used for live task updates. If the task is not currently streaming, the route can return:

{
  "error": "task_not_streaming"
}