> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autonomyai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks

> Start, poll, iterate, review, and ship coding tasks.

### `start_task`

Start a new Autonomy coding task.

Returns immediately with a task\_id and status=running; the work executes in
the background. Poll get\_task(project\_id, task\_id) to track progress.

<ParamField path="project_id" type="UUID" required>Target project UUID.</ParamField>
<ParamField path="workspace_id" type="UUID" required>Workspace UUID for the project (from list\_projects).</ParamField>
<ParamField path="instruction" type="string" required>What the agent should do, in natural language.</ParamField>
<ParamField path="initial_step" type="string">Optional starting step: 'planner', 'builder', or 'detect\_component'. Leave null to let the orchestrator route.</ParamField>

### `continue_task`

Send a follow-up message to an existing task and resume its workflow.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID to continue.</ParamField>
<ParamField path="instruction" type="string" required>Follow-up message / instruction for the task.</ParamField>
<ParamField path="step" type="string">Optional target step. Null stays on the current step.</ParamField>

### `get_task`

<Icon icon="eye" /> Read-only

Get the latest state of a task (poll this after start\_task/continue\_task).

Check the task status to know when it is done (COMPLETED / DISCARDED) or
needs input.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `list_tasks`

<Icon icon="eye" /> Read-only

List the caller's tasks for a project, most recently active first.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>

### `get_task_messages`

<Icon icon="eye" /> Read-only

Get the chat/message history for a task (what the agent has said/done).

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `get_task_pr_diff`

<Icon icon="eye" /> Read-only

Get the unified git diff the task produced — its 'Files Changed' view.

This is how you pull the agent's actual code changes back into the editor,
even before a PR exists. Served from a per-version snapshot.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="version" type="int" default="1">Version number to diff (the task's version card). Use the active version from get\_task; versions start at 1.</ParamField>

### `stop_task`

Stop a running task, cancelling its in-flight agent run.

Use this to abort a task that is going the wrong way. The task returns to a
non-running state so you can continue\_task with new guidance.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID to stop.</ParamField>

### `complete_task`

Finalize a task and send it to devs (opens/updates the PR).

Call only when the user has approved the task's changes — this is the
irreversible 'ship it' action. Runs in the background; poll get\_task.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID to finalize.</ParamField>

### `checkout_task_version`

Switch the task to one of its generated versions (its active version).

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="version_id" type="int" required>Version id to switch the task to (from get\_task).</ParamField>

### `discard_task_changes`

Discard the changes made in a task's sandbox (does not delete the task).

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `archive_task`

Archive a task (status → ARCHIVED). Non-destructive: the PR is untouched.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID to archive.</ParamField>

### `rename_task`

Set the human-facing name/title of a task.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="name" type="string" required>New human-facing task name (1–200 chars).</ParamField>

### `update_task_env`

Re-sync the task sandbox's environment after changing project env vars.

Call after set\_env\_var when a task is already running so its sandbox picks
up the new values. Runs in the background; poll get\_task.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `list_agent_histories`

<Icon icon="eye" /> Read-only

List the task's agent-history metadata (one row per agent run/turn).

Use to see which specialists ran; then get\_agent\_history\_detail for the full
trace of a single run.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `get_agent_history_detail`

<Icon icon="eye" /> Read-only

Get the full message/tool-call trace for a single agent history.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="history_id" type="UUID" required>History id from list\_agent\_histories.</ParamField>

### `list_spec_versions`

<Icon icon="eye" /> Read-only

List all versions of the task's spec/plan document, newest first.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `get_task_spec_version`

<Icon icon="eye" /> Read-only

Get the markdown content of a specific task spec/plan version.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="version_number" type="int" required>Spec version number (1, 2, 3, …).</ParamField>

### `update_spec_content`

Update the latest task spec/plan version in place (auto-save).

Creates the first version if none exists yet. Use before building to shape
the plan the agent will follow.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="content" type="string" required>New markdown for the latest spec.</ParamField>

### `create_spec_version`

Save a new task spec/plan version explicitly (keeps history).

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="content" type="string" required>Markdown for the new spec version.</ParamField>