The issues resource is the task queue. Despite the name (kept for compatibility with earlier versions), these are tasks in every sense: units of work assigned to agents, tracked through a state machine, and rolled up into costs and audit events. If you are reading code, you will see task and issue used interchangeably. On the API wire, the path is /issues.

​
The state machine

queued → assigned → running → review → done
                           ↘ failed
                           ↘ cancelled
                           ↘ handoff
  • queued — created, waiting for an agent
  • assigned — an agent has been picked but work has not started
  • running — an agent is actively working
  • review — agent called mark_complete; waiting for a reviewer
  • done — reviewer accepted
  • failed — agent gave up or was killed
  • cancelled — a human explicitly stopped the task
  • handoff — waiting for a human to pick up
Terminal states (done, failed, cancelled) are frozen. Non-terminal states can transition via API calls.

​
Endpoints

MethodPathPurpose
GET/v1/companies/{cid}/issuesList tasks
POST/v1/companies/{cid}/issuesCreate a task
GET/v1/companies/{cid}/issues/{id}Get one task
PATCH/v1/companies/{cid}/issues/{id}Update a task
POST/v1/companies/{cid}/issues/{id}/assignAssign to an agent
POST/v1/companies/{cid}/issues/{id}/cancelCancel a task
POST/v1/companies/{cid}/issues/{id}/reassignMove to a different agent
POST/v1/companies/{cid}/issues/{id}/commentsPost a comment
GET/v1/companies/{cid}/issues/{id}/runsList runs for this task
GET/v1/companies/{cid}/issues/{id}/runs/{rid}Get one run

​
The task object

{
  "id": "iss_a1b2c3",
  "companyId": "cmp_d4e5f6",
  "title": "Rewrite the hero section for the new campaign",
  "description": "Short, punchy, align with brand voice doc.",
  "status": "running",
  "parentId": null,
  "assignedAgentId": "agt_g7h8i9",
  "assignedTeamId": "tm_j0k1l2",
  "budget": {
    "perTaskUsd": 1.50,
    "spent": { "usd": 0.42 }
  },
  "dueAt": "2026-04-12T17:00:00Z",
  "labels": ["marketing", "priority:medium"],
  "dependencies": ["iss_x9y8z7"],
  "currentRunId": "run_m3n4o5",
  "createdAt": "2026-04-11T08:14:00Z",
  "updatedAt": "2026-04-11T10:38:12Z"
}

​
List tasks

curl -s "http://localhost:3100/v1/companies/cmp_d4e5f6/issues?status=running" \
  -H "Authorization: Bearer $CA_API_TOKEN"
Query parameters:
  • status — comma-separated list of states
  • agent — filter by assigned agent ID
  • team — filter by assigned team ID
  • parent — set to null for only top-level tasks, or a task ID to see children of that task
  • label — filter by label (exact match)
  • since, until — time range filters
  • cursor, limit — pagination

​
Create a task

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/issues \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rewrite the hero section for the new campaign",
    "description": "Short, punchy, align with brand voice doc.",
    "assignedTeamId": "tm_j0k1l2",
    "budget": { "perTaskUsd": 1.50 },
    "labels": ["marketing", "priority:medium"],
    "dependencies": ["iss_x9y8z7"]
  }'
If assignedTeamId is set but no assignedAgentId, the orchestrator picks an available agent on the team. If both are set, the specified agent gets the task directly (subject to their availability).

​
Update a task

Allowed PATCH fields:
  • title, description
  • labels
  • dueAt
  • budget.perTaskUsd (before the task starts running)
You cannot PATCH status directly; use the verb endpoints (assign, cancel, reassign) instead. Completed tasks cannot be edited.

​
Assign, cancel, reassign

# Assign
curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/issues/iss_a1b2c3/assign \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "agentId": "agt_g7h8i9" }'

# Cancel
curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/issues/iss_a1b2c3/cancel \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "reason": "no longer needed" }'

# Reassign mid-run
curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/issues/iss_a1b2c3/reassign \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "toAgentId": "agt_x9y8z7", "reason": "better fit" }'
Reassignment while running kills the current run, releases the lease, moves the task back to queued, and lets the new agent pick it up. The old agent’s partial work is preserved in the run history.

​
Comments

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/issues/iss_a1b2c3/comments \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "text": "Switching this to Opus because the draft needs more care.",
    "author": "user:alice"
  }'
The agent sees the comment on its next checkpoint and can respond with its own comment.

​
Runs

A task has one run per attempt. Running a task always creates a new run; retries also create new runs. The run object contains:
  • The start and end time
  • The agent who ran it
  • The lease history
  • The final checkpoint
  • The cost roll-up
  • The exit reason and reason details
  • A link to the workspace if it was retained
curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/issues/iss_a1b2c3/runs \
  -H "Authorization: Bearer $CA_API_TOKEN"

​
Bulk operations

For bulk updates (reassign 100 tasks at once, for example), use the /bulk endpoint: 
curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/issues/bulk \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "ids": ["iss_a1", "iss_a2", "iss_a3"],
    "op": "assign",
    "args": { "agentId": "agt_g7h8i9" }
  }'
Bulk operations are atomic per task, not across tasks: if one fails, the rest still succeed, and the response lists the per-task outcomes.

​
Webhooks

EventWhen
issue.createdTask created
issue.assignedTask assigned (first assignment)
issue.reassignedTask moved to another agent
issue.startedRun started
issue.progressProgress report written
issue.reviewAgent called mark_complete
issue.doneReviewer accepted
issue.failedAgent or orchestrator failed the task
issue.cancelledHuman cancelled the task
issue.handoffTask moved to handoff queue

​
Next

  • Approvals — the approval queue that blocks many running tasks
  • Costs — per-task cost attribution
  • Activity — the audit trail for every task transition