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_acme",
    "skill_id": "code-review",
    "title": "Run code-review",
    "run": true
  }
}

curl -X POST "$DASH_BASE_URL/api/v1/tasks" \
  -H "Authorization: Bearer pat_..." \
  -d '{"project_id":"pr_acme","skill_id":"code-review","title":"Run code-review","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 — tasks_status

GET /api/v1/tasks/{task_id}/status is the one read an external caller polls. 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.