upload_reference_file
Upload a non-image file (PDF / ZIP / HTML / design export) to reference in
a task, and get back a descriptor.
Images don’t go here - attach those via start_task/continue_task’s
image_url/image_base64. For any other file: upload it here, then pass the
returned descriptor object(s) as start_task/continue_task’s reference_files.
The agent reads the file from the task sandbox; a single .zip is unzipped
when extract is true.
UUID
required
Target project UUID.
string
required
The file’s bytes, base64-encoded. Max ~25MB decoded (FEI’s cap).
string
required
Original filename incl. extension, e.g. ‘spec.pdf’.
boolean
Unzip in the sandbox. Leave null to auto-pick (true only for a single .zip - e.g. a design export - else false). Set false for a PDF/HTML or a ZIP you want kept intact.
start_task
Start a NEW Autonomy coding task.
Not for follow-up work. If the user is refining, broadening, correcting, or
adding to something an existing task already covers, call continue_task with
that task’s id instead. Two tasks can’t be combined after they exist, so a
follow-up sent as a new task splits one line of work across several tasks
permanently. When you can’t tell which the user means, list_tasks and ask
before starting a new one. (An archived or discarded task is the exception:
continue_task refuses those, so a new task is correct there.)
Returns immediately with a task_id, status=running, and a ready-to-use
studio_url; the work executes in the background. Hand the user the studio_url
as-is to watch the task in Studio, don’t build your own link. Note it may
look empty for a moment while the sandbox attaches before the agent moves.
Poll get_task(project_id, task_id) for the outcome, and get_task_messages for
what the agent is actually doing - get_task’s status/step only move at coarse
boundaries and can sit unchanged for many minutes of real work, so treat the
message stream, not status, as the sign of life. Optionally attach a
screenshot/image, a Figma reference, an on-screen element, connector
references (ticket/doc URLs from connected services), or reference_files
(PDF/ZIP/HTML via upload_reference_file) to work from.
Pass base_ref to start the task from a specific existing branch.
UUID
required
Target project UUID.
UUID
required
Workspace UUID for the project (from list_projects).
string
required
What the agent should do, in natural language. If the user points at a ticket/doc by URL or issue key, you can pass it via connector_references so the Autonomy agent fetches the live source itself (see that field). Inlining the contents here also works — do that if you’ve already fetched it with your own tools.
string
Optional starting step. ‘planner’ clarifies and writes a spec, ‘builder’ writes code, ‘detect_component’ finds an existing component, ‘discover’ researches and authors a brief into Space without writing code. Null does not delegate routing — the server coerces it to ‘builder’ and injects a builder-mode hint, so always send the step explicitly.
string
Existing branch to root the task at. Must already exist on the remote. Leave null to use the project’s default branch. The task’s PR opens against this same branch.
string
Attach a screenshot/reference image by public URL.
string
Attach a screenshot/reference image as base64 (FEI uploads it).
string
Attach a Figma design URL as a reference.
object
Attach a selected on-screen element (tag + css selector).
array
References to resources in the user’s connected services (e.g. a Jira/Linear ticket or Notion page) as {connector_type, value} pairs, where value is a URL or issue key. The Autonomy agent fetches each one from the live source via the user’s connector, so you don’t have to fetch it yourself. Good default when the user references a ticket/doc. Not the only way: if that service isn’t connected on Autonomy, you can instead fetch it with your own connected tools and inline the content, or just suggest the user connect it in Studio — your choice, nothing is forced.
array
Reference-file attachments (PDF / ZIP / HTML / design export / any non-image file). Each entry is the descriptor returned by upload_reference_file - upload the file first, then pass the returned objects here verbatim. (Images use image_url/image_base64 instead; only non-image files go through here.)
continue_task
Send a follow-up message to an existing task and resume its workflow.
Prefer this over start_task whenever the request builds on work an existing
task already covers - refining, broadening, correcting, or adding to it.
Returns the task’s studio_url alongside its status; hand it to the user
as-is rather than building a link. Optionally attach a screenshot/image, a
Figma reference, an on-screen element, connector references (ticket/doc
URLs from connected services), or reference_files (via upload_reference_file)
alongside the message.
A follow-up sent while the task is mid-run comes back queued: true with a
queue_position: it is parked in the task’s change-request line and
dispatches when the current run finishes. That is a wait, not a failure - read
the next_step on the response and don’t re-send. Pass
delivery="steer" when the message CORRECTS what the run is doing right
now and waiting for it would mean correcting finished work; the default waits
for the run, which is right for a message that adds to it.
UUID
required
Project UUID.
UUID
required
Task UUID to continue.
string
required
Follow-up message / instruction for the task. To point the agent at a ticket/doc by URL or issue key, you can pass it via connector_references so the agent fetches the live source; inlining content you’ve already fetched works too.
string
Optional target step. Null stays on the current step.
string
default:"after_run"
Only matters when a run is already in flight, and only then does the message wait at all. ‘after_run’ (the default) lets the current run finish and then runs this message as its own turn. ‘steer’ joins the run already executing, at its next tool boundary, so the agent changes course before finishing the work you are correcting - ask for it when this message CORRECTS what the run is doing right now, and leave it alone when the message ADDS to a sequence the agent is part-way through. Ignored when nothing is running: there is no queue to jump.
string
Attach a screenshot/reference image by public URL.
string
Attach a screenshot/reference image as base64 (FEI uploads it).
string
Attach a Figma design URL as a reference.
object
Attach a selected on-screen element (tag + css selector).
array
References to resources in the user’s connected services (e.g. a Jira/Linear ticket or Notion page) as {connector_type, value} pairs, where value is a URL or issue key. The Autonomy agent fetches each one from the live source via the user’s connector. Optional: if that service isn’t connected on Autonomy, fetch it with your own tools and inline the content, or suggest the user connect it — nothing is forced.
array
Reference-file attachments (PDF / ZIP / HTML / any non-image file): descriptors returned by upload_reference_file, passed back verbatim. Images use image_url/image_base64 instead.
get_task
Get the latest state of a task (poll this after start_task/continue_task).
Check the task status to know whether it finished (a version is ready, or the
task was discarded) or is waiting on the user. Don’t repeat raw status values
to the user — translate them (e.g. a version awaiting review = “ready for your
review”, not “pending”).
Once the task has been sent to devs the response carries a top-level
pr_url - hand the user that link rather than looking the PR up on the git
provider. It is absent before the task ships.
For a sent task this also reconciles PR merge/close state first, so it can
flip the task to merged / closed rather than being a pure read. The
reconcile is project-scoped, so sibling sent tasks can flip too. Safe to
call repeatedly: the write only ever copies what the git provider already
says, and re-reading changes nothing further.
UUID
required
Project UUID.
UUID
required
Task UUID.
get_task_queue
Read-only
Read a task’s change-request line: what is still waiting, and what was refused.
Call this when continue_task answered queued: true and the follow-up
looks like it went nowhere.
queued is the shared line in run order - every participant’s rows, each
with its position - 1-based, and a run in flight holds slot 1, so while
the task is working the first waiting row is 2. Those dispatch on their own
when the run ahead ends; nothing here needs doing about them.
refused is what get_task cannot tell you. A change request the dispatch
gate turns down terminally - the author may no longer send to devs, a
connector connection is gone - leaves the line and never runs, while the
task keeps reading “running” off the run ahead of it. Each entry carries the
row id, its author_user_id and the failure_reason: report that
reason to the user rather than re-sending blind. Only your own refused rows
are listed, because only their author can act on them. They carry
position: 0 - out of the line, not at the head of it - and stay listed
until dismissed in Studio, so use created_at (newest first) to tell a
fresh refusal from one you have already reported.
A refused entry with no failure_reason is out of the line but was not
necessarily turned down - a row can leave it by being delivered another way -
so check the task’s messages for whether that request ran before re-sending
it. next_step says which of the two you are looking at.
UUID
required
Project UUID.
UUID
required
Task UUID.
list_tasks
Read-only
List a project’s tasks, most recently active first.
Returns only the first 50 tasks and cannot page past them — older tasks
are not reachable through this tool, so don’t treat the result as the
project’s full history. The response carries next_cursor/has_more for
reference, but there is no cursor parameter to send it back with.
Scope follows the caller’s role: a normal user sees their own tasks, a
SuperAdmin sees every user’s tasks in the project.
UUID
required
Project UUID.
refresh_pr_status
Reconcile the merge/close state of a project’s recently sent-to-devs tasks.
Once a task is sent to devs its PR is open with the dev; use this to pick up
whether the dev has since merged it or closed it without merging. It reads the
live PR state and flips affected tasks to merged / closed. Returns how many
tasks changed — re-read get_task to see a task’s new status (get_task already
does this refresh itself for a sent task). Call this when the user asks about
their PR; don’t poll it on a loop.
UUID
required
Project UUID.
get_task_messages
Read-only
Get a task’s chat timeline (newest first) - the full transparency surface.
Each message carries typed parts: user text/attachments, agent reasoning and
tool calls (tool name, args, result), version cards, and any PENDING
approval/question cards with the deferred tool_call_id you’d pass to
approve_task_tool_call, answer_task_question, or (for a setup task)
reply_setup_approval. Page with cursor/next_cursor; window big pages with
offset.
UUID
required
Project UUID.
UUID
required
Task UUID.
string
Opaque page cursor from a previous response’s next_cursor. Omit for the newest page.
int
Page size in user-message turns (server default 50).
int
default:"0"
Character offset into the response for paging large payloads; use next_offset from the previous call.
get_task_pr_diff
Read-only
Get the code diff a version produced — Studio’s ‘Files Changed’ view.
This is how you pull the agent’s actual code changes back into the editor.
Call it the “code diff” / “Files Changed”, not a “PR diff” — no PR exists
until Send to Devs. Served from a per-version snapshot.
UUID
required
Project UUID.
UUID
required
Task UUID.
int
default:"1"
Version number to diff (the task’s version card). Use the active version from get_task; versions start at 1.
int
default:"0"
Character offset into the response for paging large payloads; use next_offset from the previous call.
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.
UUID
required
Project UUID.
UUID
required
Task UUID to stop.
complete_task
Finalize a task and send it to devs (the ship flow, same as the Studio
‘Send to Devs’ button).
Call only when the user has approved the task’s changes — this is the
irreversible ‘ship it’ action. The agent cleans up, commits, and pushes the
branch, then pauses on a create_pr approval card. Runs in the background:
poll get_task, and when it stops on the approval, read get_task_messages for
the create_pr tool_call_id + orchestration_conversation_id and call
approve_task_tool_call to open the PR.
Expect to approve more than once: each create_pr attempt raises its own card
with a new tool_call_id, so keep re-reading get_task_messages for a pending
card until the PR exists (get_task’s pr_url) or the task leaves running.
UUID
required
Project UUID.
UUID
required
Task UUID to finalize.
approve_task_tool_call
Approve (or reject) a tool call a task is paused on — most commonly the
create_pr card raised by complete_task / Send-to-Devs.
Resumes the task in the background. Approving a create_pr card does NOT
guarantee the PR: the orchestrator can retry the handoff and raise another
card with a different tool_call_id, which this approval doesn’t cover. So
don’t treat one approval as the end of the ship flow - while the task is still
running, re-read get_task_messages for a pending approval card and approve
that too. The PR is done when get_task returns a pr_url.
UUID
required
Project UUID.
UUID
required
Task UUID.
string
required
The deferred tool_call_id from the task’s tool_approval_request message (see get_task_messages).
boolean
default:"True"
True to run the tool (e.g. open the PR), False to reject.
UUID
The orchestration_conversation_id from the same tool_approval_request message. Pass it so the orchestrator resumes the paused run rather than starting a new one.
answer_task_question
Answer a task’s clarifying question (PLANNER’s ask_user_question) and
resume the workflow. Resumes in the background; poll get_task.
UUID
required
Project UUID.
UUID
required
Task UUID.
string
required
The deferred tool_call_id of the agent’s ask_user_question card (see get_task_messages / the planner_card).
object
required
Answers keyed by the question’s field id, e.g. {“framework”: “react”, “styling”: “tailwind”}.
get_task_studio_url
Read-only
Get the Studio deep link for a task — open it in the browser to watch or
drive the task in the Autonomy web app.
Works at any point in the task’s life (running, sent to devs, merged,
discarded, or archived); hand it to the user whenever they want to see
the task in Studio, not only while the agent is working.
UUID
required
Project UUID.
UUID
required
Task UUID.
checkout_task_version
Switch the task to one of its generated versions (its active version).
UUID
required
Project UUID.
UUID
required
Task UUID.
int
required
Version id to switch the task to (from get_task).
discard_task_changes
Discard the changes made in a task’s sandbox (does not delete the task).
UUID
required
Project UUID.
UUID
required
Task UUID.
archive_task
Archive a task (status → ARCHIVED). Non-destructive: the PR is untouched.
UUID
required
Project UUID.
UUID
required
Task UUID to archive.
unarchive_task
Restore an archived task (status → SENT if it had a PR, else PENDING).
Non-destructive; the inverse of archive_task.
UUID
required
Project UUID.
UUID
required
Task UUID to unarchive.
rename_task
Set the human-facing name/title of a task.
UUID
required
Project UUID.
UUID
required
Task UUID.
string
required
New human-facing task name (1–200 chars).
toggle_task_pin
Pin or unpin a task in the sidebar’s recent-tasks list (idempotent).
UUID
required
Project UUID.
UUID
required
Task UUID.
boolean
required
True to pin the task, False to unpin.