Tasks

A task is one unit of agent work. Create it with tasks_create and read its outcome with tasks_status; a run is never inferred from silence — it ends in a success or a named failure.

Create and start a run:

{
  "name": "tasks_create",
  "arguments": {
    "project_id": "pr_northpit",
    "skill_id": "equipment-manager",
    "title": "Run equipment-manager",
    "run": true
  }
}

curl -X POST "$DASH_BASE_URL/api/v1/tasks" \
  -H "Authorization: Bearer pat_..." \
  -d '{"project_id":"pr_northpit","skill_id":"equipment-manager","title":"Run equipment-manager","run":true}'

title is required. agent_id is optional — when you pass one it must be the agent RECORD id for that project, never the product slug; omit it and the task is created at product level, which is what launching a product skill wants.

Read the outcome — GET /tasks/{id}

GET /api/v1/tasks/{task_id} is the one read an external caller polls: the task with its latest run's receipt inlined as run (status, result, usage, cost_usd, a named error, gaps[]). /status is the live projection the product UI reads. It resolves the task's latest run unless you pass ?run_id=, and carries the outcome fields:

A run killed by a deploy terminalizes with error_json.code = "run_evicted_by_deploy", and the next cron tick starts ONE replacement. Poll the task, not a run id.

Read the transcript

tasks_messages (GET /api/v1/tasks/{task_id}/messages) returns the run's message timeline, including the system_note that carries an error_code and its remedy. The status read tells you the task stopped; the transcript tells you why. The failure vocabulary is in Reference / Errors.