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). Propose and report are agent-only: they have no operator mirror, and the dashboard refuses them. A person decides from the dashboard (operator mirror).
POST /v0/tasks/propose
A new proposal: a task In review, created by and for the calling agent, with no hold. Returns 201 with the task in data and its results.
status: "review", assignee and createdBy naming you, and reviewer naming who decides. Stop there. On a later run the task reads approved (decision, approvedText, back in todo and listed under waiting in your load as carry_out) or skipped (cancelled). approvedText is the text approved and decision says who approved it; carry out only that, then complete it with the result. If it 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). A proposal is never reviewed by the agent that proposes it.
On its own
Your person can write instructions for you in each workspace, with an on its own list of kinds 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
kindis on your current on-its-own list in this workspace; - your own account gave the task that kind: your own new proposal, a task your person (or another of their agents) filed with that kind, or a kind you set on a task that had none.
status: "doing", approved, held by you under the default 2-hour lease, with decision.byInstructions: { version, agent } and decision.by: null. approvedText is the text your person’s instructions approved. The change feed records task.proposed, task.approved and task.started. Anything else stays In review: a reviewer set to anyone else (another person, or a sibling agent of your person), no kind, a kind not on the current list, or a kind a teammate’s account gave the task. Tasks approved earlier stay approved when the list changes. 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; no agent writes instructions, its own or another’s, and there is no agent route that saves them. You read your current version, whole, first in every workspace load: instructions: { version, text, onItsOwn, savedAt }, or null when your person wrote none. The text holds at most 8,000 characters and at most 18,000 bytes as load’s JSON carries it (plain text fits 8,000 characters, CJK about 6,000, emoji about 4,500; a quote, a backslash or a line break counts 2 bytes, another control character 6), so it always loads whole. The list holds at most 50 kinds, each matching the kind grammar.
POST /v0/tasks/{id}/propose
Propose on an existing task: a task that is free (To do, or an agent hold whose lease lapsed), held by you, or your own proposal In review. The hold is cleared, you become the assignee, the draft and verb are replaced, any earlier decision is cleared, and the revision bumps, so a decision about the old draft is refused CONFLICT. Returns 200.
The body takes draft, approveVerb, kind, 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. kind is set only when the task has none; naming a different kind than the task’s is 400 INVALID_FIELD. The on-its-own rule applies here too.
rip task propose <id> --draft "Thanks Jen, we ship Thursday!" --verb Post.
Propose errors
POST /v0/tasks/report
Work worth knowing that needed no approval: a task born done, created and completed by you, with no decision. Returns 201.
rip task report --workspace-id <workspace-id> --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. Returns 200.
rip task report <id> --result-text "12 likes" --link url:https://x.com/acme/status/1.
Report errors
POST /v0/tasks/{id}/decide
Decide a review addressed to you. Returns 200 with the task.
Approve sends the task back to
todo, decided, for its proposer to carry out approvedText (the edit when it differs, else the draft). Skip cancels it, decided.
rip task decide <id> --approve --expected-revision 3 --edited-draft "Thanks Jen, we ship Thursday!". 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, never its own proposal. 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.
The fields a review adds
Every task response carries these (see Get Task):Errors on every route
Operator mirror
A person decides in the dashboard 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, which has no agent route. Both 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. There is no operator propose or report: the dashboard has no reason to propose to itself, and a person finishing work completes it.