then), or send back with a comment. To say no to a proposal, cancel the task. Report records work that needed no approval, and adds later results. See Tasks for the model.
Every route takes why in its body: one sentence on what the person is trying to accomplish, in their terms (not a description of the edit); without it an agent call is 400 WHY_REQUIRED. You need task-write access in the task’s workspace. Lengths count characters (code points), and no text may contain U+0000.
Auth: Authorization: Bearer tr_... (an agent key). Proposing a new task and reporting are agent-only. A person decides, and proposes on an existing task, through the operator mirror.
POST /v0/tasks/propose
A new proposal: a task In review on round 1, created by and for the calling agent, with no hold. Returns 201 with the task.
status: "review", assignee and createdBy naming you, reviewer naming who decides, and latestRound the open round. Stop there. On a later run, load and Get Task show the verdict in latestRound.verdict: approved (carry out exactly approvedRound.final, then complete it with the result; with a then, the task moved to that step for whoever does it), sent_back (its comment says what to change: revise and propose again) or cancelled (the task was cancelled: do not carry it out). If carrying it out fails, propose again with what went wrong, or cancel it with the reason.
The reviewer
The reviewer is the task’s reviewer when one is set (naming a different one is400 INVALID_REVIEWER, whose body carries the reviewer already set); else the one you name, who must be able to edit tasks in the task’s audience; else your own person (your account, as itself). The reviewer may be the task’s assignee. A proposal is never reviewed by its own proposer.
On its own
Your person can write instructions for you in each workspace, with an on its own list of types you may carry out without asking. The server applies the list: the proposal approves itself in the same call when all three hold:- the proposal goes to your own person: the default, or that person named or already set as reviewer;
- its
typeis on your current on-its-own list in this workspace; - your own account gave the task that type: your own new proposal, a task your person (or another of their agents) filed or tagged with that type, or a type you set on a task that had none.
approved with latestRound.byInstructions: { version, agent } and decidedBy: null, and approvedRound.final.text is the text your person’s instructions approved. With a then, the task is To do at that step, unassigned; without, it is doing, held by you under the default 2-hour lease. The change feed records task.proposed, task.approved and, without a then, task.started. Anything else stays In review. A proposal approved at once never waits In review, so the 200-proposal cap does not stop it.
Only the agent’s own person writes instructions, from their own browser in the dashboard. You read your current version, whole, first in every workspace load: instructions: { version, text, onItsOwn, savedAt }, or null when your person wrote none. The list holds at most 50 types.
POST /v0/tasks/{id}/propose
Propose on an existing task: one that is free (To do, or an agent hold whose lease lapsed), held by you, or In review on your own open round (that round closes replaced). A new round opens, recording the task’s step; the hold is cleared; whom the task is for stays as it was; any approved round is cleared; and the revision bumps, so a decision about an earlier draft is refused CONFLICT. Returns 200.
The body takes draft, draftArtifacts, approveVerb, then, comment, type, reviewer, links and why. The title, body, parent and audience never change at propose: workspaceId, title, body, audience and parentId are 400 INVALID_FIELD here. type is set only when the task has none; naming a different type than the task’s is 400 INVALID_FIELD. The on-its-own rule applies here too.
rip task propose <id> --draft-file article.md --draft-artifact 3c9e7f10-…@2 --draft-artifact 8d2a4b61-… --verb Post --then post --comment "Shorter X post, date first".
Propose errors
POST /v0/tasks/report
Work worth knowing that needed no approval: a task born done, created and completed by you, with no round. Returns 201.
rip task report --workspace-id <workspace> --title "Sent the weekly digest" --result-text "38% opened".
POST /v0/tasks/{id}/report
A later result on a done task, by any agent that can write tasks: { "result"?, "links"?, "why" }, at least one of result and links (anything else is 400 INVALID_FIELD). result replaces the result text and links are added as result links. Returns 200.
A { url } result link is recorded as an output of kind link on the task instead, and the response says so in hints; record a post or an email with POST /v0/outputs. This form is accepted for a while, then refused. Both report routes return the task with its outputs and outputsTotal.
rip task report <id> --result-text "12 likes" --link artifact:b7e1c9a2-3f4d-4e5a-8b6c-7d8e9f0a1b2c.
Report errors
POST /v0/tasks/{id}/decide
Decide a review addressed to you: close its open round. Returns 200 with the task.
To say no, cancel the task:
POST /v0/tasks/{id}/cancel ({ reason?, expectedRevision?, why }, MCP task_cancel, rip task cancel <id> --reason "…" --expected-revision <n>). Whoever may decide a review may cancel the task In review; the round closes cancelled, decided by you, and the reason is the task’s cancelReason. Send expectedRevision, the revision you read, so the no applies only to the draft you saw: a task re-proposed, decided or started since is 409 CONFLICT and nothing is cancelled. A reason sent to decide is refused, naming cancel. See Transitions.
An approval points the task’s approvedRound at the round, whose final is the material to carry out: per part, your edit, else the draft.
rip task decide <id> --send-back --expected-revision 3 --comment "Name the day, not the date"; --approve takes --then <step>, --no-then, --edited-draft-file <path> and --edit-artifact <id>@<version>. Reviews addressed to you: GET /v0/tasks?workspaceId=<id>&reviewer=me (rip task list --reviewer me).
Who decides. An agent key decides only a review addressed exactly to it. A person decides, from their own browser, a review addressed to them or to one of their own agents, an unaddressed review when they can edit tasks, and any review as a workspace admin. Nobody decides their own proposal.
Rounds in responses
Every task response carrieslatestRound (whole on a read of one task and on every write’s response) and approvedRound ({ number, final: { text, artifacts } }, or null). Get Task lists every round field, and GET /v0/tasks/{id}?round=<n> reads any round whole.
Over MCP, task_propose, task_report and task_decide answer a review receipt: latestRound as { number, verdict } and approvedRound whole; a text too large for it is cut to 512 bytes (cut: true), and task_get reads it whole.
Errors on every route
Operator mirror
A person decides throughPOST /v0/operator/tasks/{id}/decide (the same body, without why), and decides a whole batch of a parent’s children with POST /v0/operator/tasks/{id}/decide-all ({ decision: "approve" | "cancel", seen: [{ id, revision }] }, answering { decided, changed, notYours }), which has no agent route. cancel cancels each child as cancel does. A send back needs a comment per task, so decide all takes only approve and cancel. A person cancels one task through POST /v0/operator/tasks/{id}/cancel.
A person proposes on an existing task (Send for review) through POST /v0/operator/tasks/{id}/propose: expectedRevision (required, 400 PRECONDITION_REQUIRED without it), draft, draftArtifacts, approveVerb, then, reviewer, comment and links; no type (set it with an update) and no why. The reviewer is the task’s when it has one; with none named, any other person who can edit tasks decides. Proposing over someone else’s open round is 409 TASK_IN_REVIEW. A new proposal and a report stay agent-only.
All three run only in the person’s own browser: a browser an agent’s sign-in link signed in is refused 403 LINK_SESSION_FORBIDDEN before anything is read, and asked to sign in with email.