done), record each run in the run ledger, link dependencies, and manage a task’s git worktree: create it, read it, pause or complete it, browse its files and preview what the agent built. A task with no worktree has its own folder instead, which they browse and preview the same way.
Several routes also post a short system line to the team’s peer room, the agents’ shared room behind the TeamChat tools (see Peer chat). The dashboard’s team chat does not show those lines, and a failed post never fails the request.
Every POST and PATCH body is validated. An invalid body returns 400 { "error": "invalid body", "details": <zod flatten> }; the handoff route returns { "error": "invalid handoff", "details": ... } instead. Every route here is on the general rate tier (see rate limits).
Retry, Assign, creating a task for a named agent or for yourself, completing a worktree, Reopen, assigning a task to a person, answering a question, answering the card about agents waking each other, a task’s labels, a read mark, a status change and a
user comment act for a person, so they go through the person check: the request must come from the dashboard’s own page, or from a person a sign-in proxy vouched for. All but the status change and the comment refuse any other caller with 403 person_only, in { "ok": false, "error": "person_only" } or { "error": "person_only" }. A status change from another caller still happens, without a person’s authority (see PATCH below). A script acting for you can send Sec-Fetch-Site: same-origin and Sec-Fetch-Mode: cors, as the examples below do. This is a speed bump on your own computer: agents run as your user account and can send the same headers.A claim is how agents share work without doing it twice:
POST /api/board/:taskId/claim answers 409 when another worker already holds the task. A 409 is an answer, not a transient error; do not retry it. The task is simply taken. The same applies to 409 illegal_transition on PATCH /api/board/:taskId.Routes
Task statuses
A task is in one of seven statuses:backlog, todo, in_progress, in_review, blocked, done, cancelled. done and cancelled are final. Writing the status a task already has is allowed and changes nothing. Any move not in this table is refused with 409 illegal_transition:
Moving a task to
todo clears its assignee and its check result, so it can be claimed again.
GET /api/board
Lists tasks, for one team or all of them, or only the tasks that are ready to work. With ready=true the list holds todo tasks that are not dropped and whose dependencies are all done, in the order they are served: tasks that ran before first, then aged priority, then oldest first. A task a pause covers is still listed there. Each row of the full list, and task in GET /api/board/:taskId, carries pause: the pause covering the task, or null. Otherwise it is filtered by teamId, status and includeDropped. Dropped (soft-deleted) tasks are left out unless includeDropped=true.
- Query params:
- Request body: none.
Responses
200 OK: the task list, most recently updated first (the ready=true list keeps the order at the top of this section). The ready=true rows carry none of attention, runCost, runningSince and jobStopped. Other sections call one of these rows DbTask:
attention comes from the task’s status, its bound agent (the :agent: segment of sourceDelegationId), its run ledger, its check result, what it waits on and who it is assigned to. The task at the top of a job that has started as many runs by itself as it may is job_limit, ahead of every other reason and whatever its status, until a person answers with POST /api/board/job-limit/:jobTaskId. A blocked task whose agent’s comment still waits on the card about agents waking each other is agent_wakes, with agentWakes: { jobTaskId, kind, fromAgentId, toAgentId, alsoWaiting?, openedAt? }. alsoWaiting counts the other tasks that wait on the same answer, and a card nothing waits on any more is not shown. openedAt is when the card opened: it stays the same while the card does, and moves when another pair or kind takes the card, or the card comes back after an answer. checkFailed is there when the task’s verdict also cannot be promoted, which the card does not change. A question waiting for its answer is question, and an open task assigned to a person is assigned, unless it is in backlog; both come first. A blocked task has one, unless it waits on another task or its sub-tasks: no_result, out_of_room, rate_limited or provider_down, or budget from what it waits on; else needs_review when its verdict cannot be promoted; else blocked for what an agent said a person must do; else budget, breaker, timed_out or failed from its last run; else needs_review when it waits on a check; else blocked. A check whose move to Blocked keeps failing is needs_review while still in_review or in_progress. A todo task has one only when nothing will fire it: no bound agent (unassigned), a last run the user stopped (stopped), a hard budget cap (budget), the circuit breaker (breaker), or three failed runs in a row (failed / timed_out). An in_progress task with no assignee and no running run is unstarted: nothing is working on it. The board renders every task with an attention in its Needs you column.
runCost sums the costUsd of the task’s run ledger rows. A row with no cost (a run stopped before it priced itself) adds nothing, and usd stays null until some run records one. estimated is true unless every counted row has costSource 'reported' or 'local'; a row with a null source counts as an estimate. local: true appears only when every counted row is 'local', a run on a model the user’s own Ollama served, and the board then shows the cost as free. A task whose rows carry no cost but whose own costUsd is positive predates per-run costs, so that figure is returned with estimated: true.
500 Internal Server Error: a database failure:
Example
POST /api/board
Creates a task. status defaults to todo (ready to be claimed); pass backlog to park it. On success the route writes a task_created event to the event log; a failed event write never fails the request.
Set parentTaskId to make a subtask. This route applies no child-count or depth limit (the Tasks MCP server’s create_subtask and the team engine’s hand-offs do; see MCP tools), and it does not copy the parent’s team or room. A parentTaskId that does not exist fails the database’s foreign key and answers 500.
- Path/query params: none.
- Request body:
sourceDelegationId takes the person check when it names an agent (:agent:<id>), who hears the result (:reflectTo:<id>) or says a person chose (origin:human): the engine reads those as a binding and fires it. Any other caller gets 403 person_only, with nothing written.
assignToMe makes the task the sender’s own: nothing starts it. It cannot go with assigneeAgentId (400 one_assignee), and a request that does not pass the person check gets 403 person_only. A task created from the dashboard’s page, or by a person a sign-in proxy vouched for, records them in requestedBy, which is where an agent’s hand-back goes.
With idempotencyKey (the New task dialog sends one per draft), a repeat returns the task the key first made, with deduplicated: true beside task. It writes no event and starts no run. This route skips the same-title check that agents’ creates go through: a person’s two tasks with one title are two tasks.
With assigneeAgentId (the board’s New task dialog), the task is created for one agent, which takes the same check: teamId is required, the agent must be an active member of that team, and status may only be todo (the default) or backlog. The server writes a sourceDelegationId that binds the task to the agent and marks it as assigned by a person, then, for a todo task, hands it to the team’s engine to run now (the response does not wait for the run to start). The agent receives the title and description together. Its result is recorded on the task (the report comment) and is not delivered to the team lead as a task update: a person-assigned task reports to the person, on its card. If the agent is busy, the task waits in todo and runs when the agent is free.
Responses
403 Forbidden: { "ok": false, "error": "person_only" }: assigneeAgentId or a sourceDelegationId naming an agent was set, and the request did not pass the person check. Nothing was written.
400 Bad Request: body failed validation ({ "error": "invalid body", ... }), or, with assigneeAgentId: team_required, agent_not_in_team (unknown, archived, or on another team), or invalid_status:
200 OK: the created task, shaped as a GET /api/board row with attention and runCost (no runningSince):
500 Internal Server Error: a database failure, including an unknown parentTaskId:
Example
GET /api/pauses
Every pause, oldest first. A person pauses an agent, a team or a task tree, and nothing it covers starts until they resume it; see Pause work. A pause whose agent or team has been deleted is not listed.
POST /api/pauses
Pauses it, and stops the runs it covers without waiting for them: the pause holds as soon as this answers. Pausing something already paused changes nothing, and the first pause’s reason and time stand. It takes the person check.
- Request body:
{ kind: 'agent' | 'team' | 'task', id: string, reason?: string }.tasknames any task in a tree, and the tree is paused from its root.reasonis at most 200 characters.
201 Created when this paused it, 200 OK when it already was: { ok: true, created: boolean, pause }.
400 Bad Request: a bad kind, id or reason. 403 Forbidden: { "ok": false, "error": "person_only" }. 404 Not Found: { "ok": false, "error": "not_found" }.
DELETE /api/pauses/:kind/:id
Resumes it, and waiting work starts again at once. :kind is agent, team, task (any task in the tree) or task_tree. It takes the person check.
200 OK: { ok: true }. 403 Forbidden: { "ok": false, "error": "person_only" }. 404 Not Found: { "ok": false, "error": "not_paused" }.
Main tasks
A row withisMainTask: 1 holds a person’s request from the chat: their words, who asked (requestedBy), the agent looking after it (assigneeAgentId), and the work filed under it (parentTaskId). It sits in_progress with waitingOn: {"kind":"subtasks"} until its lead’s summary, and holds no run.
POST .../retryandPOST .../executionsanswer 409main_task.POST .../assignanswers 409not_assignable.POST .../claimanswers 409conflict.POST .../commentsfrom a person passes their words to the agent looking after it, and answersdelivery: { status: "woke-agent" }, orqueuedwithheldwhile new runs are held andpausedwhile a pause covers it. On a closed one it answersnot-deliveredwithfinished.POST .../reopenmoves it back toin_progress, nottodo, and passes the person’s words, or a line saying they reopened it, to that agent. Reopening a sub-task under a closed main task reopens the main task too.GET /api/board/:taskIdaddssubtasks: everything filed under it, at any depth, oldest first, each with itsattention.POST /api/boardunder a closed main task, at any depth, works and opens that main task again. An agent’screate_subtaskanywhere under one answers withmain_closed.
POST /api/board/:taskId/retry
Runs a stuck task again because a person asked: one that failed, timed out, was stopped, or was parked after failing three times in a row. A blocked, backlog or stranded in_progress task (no assignee and no run going) is moved back to todo first, which clears its assignee and check result. The route adds a user comment Retry requested. to the task and hands it straight to its bound agent. The board’s automatic limit of three re-runs does not apply to a retry a person asks for. The response does not wait for the run to start.
A task the task runner ran (an agent Routine, or POST /api/runtimes/:id/run) has runnerInputs, and goes back through the runner with them: the same repository and isolation kind, so it gets a worktree when the task names a repository, and its check again. Its agent is the bound one, else the one the runner ran it for, and it needs no team. The run uses that agent’s runtime, and the saved model only on the saved runtime. A removed agent runs nothing, and neither does an id with no agent row unless it is the saved runtime’s own id (the id the run route uses when it names no agent). When the runner cannot run the agent, such as one on OpenClaw, the task goes to team chat if an agent is bound to it, and answers 409 unassigned if none is. A task with no runnerInputs, which includes tasks the runner ran before it started saving them, goes to its team’s chat as before.
A runner rerun that does not start (the runner refuses it, for example because a budget is paused at its hard cap, or it times out waiting for the agent) moves the task to blocked with a system comment that gives the reason. A Retry or Assign stops a rerun of the same task that is still waiting to start. Team chat never fires a task the runner reruns: when its run fails and it goes back to todo with an agent bound, the server re-fires it through the runner, under the same three-runs limit.
- Path params:
taskId. - Request body: none.
Responses
202 Accepted: the task as it now stands, in todo:
403 Forbidden: { "ok": false, "error": "person_only" }: the request did not pass the person check. Nothing was written. To put a stuck task back without a person’s authority, move it to todo with PATCH, where the board’s automatic limits still apply.
404 Not Found: { "ok": false, "error": "task not found" }.
409 Conflict: { "ok": false, "error": "<reason>" }, where the reason is not_retryable (the task is running, finished or cancelled), no_team (it has no team and is not a task-runner rerun), unassigned (no agent is bound to it, and the runner cannot rerun it for the agent it ran it for; use assign), room_archived (it would run in team chat, but it is still filed under an archived chat room, where no engine can see it), or paused (a pause covers it, or its team is archived; resuming starts it). Every refusal comes before anything is written. room_archived happens only for a task the archive’s move to General missed; the move runs again each time Clawboo starts (see DELETE /api/teams/:id/rooms/:roomId). A task filed under a room that no longer exists gets no_team: rooms are removed only with their team, so there is no chat left to run it.
500 Internal Server Error: { "ok": false, "error": "<message>" }.
Example
POST /api/board/:taskId/assign
Gives a task that nobody is working on to one member of its team, and starts it. Use it for a card no agent will pick up (created without one, or by an agent’s own create_task), or to hand a failed task to someone else. The task is bound to the agent as a person’s assignment (see POST /api/board), moved back to todo if it was blocked, backlog or stranded in_progress (no assignee and no run going), noted on its trail (Assigned to <name>.) and started. When the agent is not the one it was bound to, every agent’s saved session on the task is cleared, so the new agent starts fresh and so does an earlier one if the task comes back to it. Assigning it to the same agent again keeps that agent’s session, like a retry.
A task with runnerInputs starts through the task runner, on the new agent’s runtime, with the saved repository and isolation kind; the saved model is kept only when the runtime is the same. An agent on a runtime the runner cannot run, such as OpenClaw, and a task with no runnerInputs, start in team chat. See retry above.
- Path params:
taskId. - Request body:
{ agentId: string }.
Responses
200 OK: { "ok": true, "task": DbTask }.
400 Bad Request: { "ok": false, "error": "agentId required" }, or agent_not_in_team (the agent is unknown, archived or on another team).
404 Not Found: { "ok": false, "error": "task not found" }.
403 Forbidden: { "ok": false, "error": "person_only" }: the request did not pass the person check. Nothing was written.
409 Conflict: no_team, not_assignable (the task is being worked on, finished, cancelled or dropped), or room_archived (as for retry: it would start in team chat but is still filed under an archived chat room). no_team also covers a task whose room went with its team. A refusal binds nothing and writes no note.
500 Internal Server Error: { "ok": false, "error": "<message>" }.
Example
POST /api/board/:taskId/reopen
A person reopens a done or cancelled task: it goes back to todo, with completedAt and personCancelledAt cleared, and a note on its comments. A saved wake starts it, so a restart cannot lose the start or the words. With comment, its agent starts with those words. Without one, a task bound to an agent starts as a retry starts it. A task assigned to a person goes back to them and starts nothing, and a task with no agent waits in Needs you. A finished task’s saved sessions are already cleared, so the run starts fresh. Plan steps cancelled along with it stay cancelled.
A person’s route. It answers 403 { "ok": false, "error": "person_only" } to a request that does not pass the person check. A speed bump on a local install: see What counts as a person. The moves are not in the status table, so PATCH /api/board/:taskId cannot make them.
- Request body (optional):
200 OK: { ok: true, task: DbTask, delivery?: ReplyDelivery }. delivery says where a comment went, as on a person’s comment, and is also present when a task with no comment could not start. A reopened task whose words reached no one still answers 200: read delivery.
404 Not Found: no such task. 409 Conflict: { "ok": false, "error": "not_finished" }, or "blocker_cancelled" for a task that depends on one that was cancelled or dropped: nothing would ever start it, so reopen that one first.
POST /api/board/:taskId/assign-person
Gives a task nobody is working on to a person. It takes any agent off it, including the agent binding, so nothing starts it and a comment reaches no agent. Whoever delegated it is still told when it finishes. Every agent’s saved session on it is cleared. A blocked or stranded in_progress task goes to todo. Any open question closes.
A person’s route, like reopen. There is no member list, and a request body never makes a person: personId may name only the sender or the person who asked for the task.
200 OK: { ok: true, task: DbTask, attention }. 400 Bad Request: { "ok": false, "error": "unknown_person" }. 404 Not Found: no such task. 409 Conflict: { "ok": false, "error": "not_assignable" }: the task is being worked on, finished, cancelled or dropped.
GET /api/board/:taskId/questions
The questions agents asked on a task, oldest first: { questions: DbTaskQuestion[] }. See task_questions.
POST /api/board/agent-wakes/:jobTaskId
A person answers the card about agents waking each other on a job. Yes also starts the job’s hour and the two agents’ count again, which lifts a pause, and starts what was waiting. An answer to the first ask also covers the other tasks waiting on it (alsoWaiting). No Tasks tool can do this.
A person’s route, like reopen.
- Path param:
jobTaskId: the job’s task, fromattention.agentWakes.jobTaskId. - Request body:
200 OK: { ok: true, task: DbTask, attention: TaskAttention | null }, for the task the card showed on.
400 Bad Request: a wrong body. 404 Not Found: no such task. 409 Conflict: { "ok": false, "error": "no_card" } when no card is up or nothing waits on it any more, so a second press changes nothing, or "no_team" for team on a job with no team.
POST /api/board/job-limit/:jobTaskId
A person answers the card on a job that has started as many runs by itself as it may. Carry on allows another 100 from where it stands, and starts what was waiting. Stop is about this job alone, with or without a team: it ends the runs going under it on the team engine and the task runner, holds what was on its way, and starts nothing more by itself, so the card stays down. Other work in the room goes on. A person’s Retry, comment or Reopen starts work again, and the job’s next refusal may bring the card back.
A person’s route, like reopen.
- Path param:
jobTaskId: the task at the top of the job, fromattention.jobLimit.jobTaskId. - Request body:
200 OK: { ok: true, task: DbTask, attention: TaskAttention | null }.
400 Bad Request: a wrong body. 404 Not Found: no such task. 409 Conflict: { "ok": false, "error": "no_card" } when no card is up, so a second press changes nothing.
POST /api/board/questions/:questionId/answer
A person answers an agent’s question. The question goes on the task’s comments under the agent that asked it, the answer goes there in the person’s name, and the task starts again for its agent, as a person’s reply starts it. No Tasks tool can do this.
A person’s route, like reopen. It records the verified person, or the install’s built-in one, as answeredBy. Behind a sign-in proxy in required mode, every request here also needs a verified person.
done or cancelled, is dropped or moves on, when a newer question replaces it, or, for a plan, when a person presses Stop, and an answer that loses that race changes nothing.
200 OK: { ok: true, question: DbTaskQuestion, task: DbTask, delivery: ReplyDelivery }. The answer is saved even when delivery.status is not-delivered. The task then stays Blocked, and its attention.detail says the answer could not start the agent. Under a pause, delivery.reason is paused, the task stays Blocked, and its attention.detail says the agent gets the answer after the resume. 400 Bad Request: invalid_answer, an answer this question does not allow. 403 Forbidden: person_only. 404 Not Found: not_found. 409 Conflict: answered, expired or cancelled.
On a plan, a question whose payload.plan names a revision of the task’s plan, the answer does more, in the same write. Accepted, it creates the steps once, chained in order, or all ready at once when payload.plan.parallel says the question came from a batch of hand-offs. What runs is what was sent: description when there is one, else title, with title only the start of it. Each step goes to the agent its entry names, if the plan named that agent, and otherwise to the agent that proposed it. A step an open task with the same words already covers is not created again, and that task holds its place. Turned down, it creates nothing. Either way the revision records the decision and who made it. The response adds created and alreadyOpen, the two counts.
The proposing agent hears the answer. On the run’s own task, as with any question, a saved wake starts that task again. On a card that only held the plan (payload.plan.holder), the same write closes the card, done or cancelled, and adds a [Task Update] to the outbox for the agent’s chat. No run starts on the card, and delivery is queued.
A plan’s refusals leave the question open, so the person can answer again:
GET /api/board/:taskId/plan
A task’s plan document. ?revision=N asks for that revision, and an older one stays readable after a newer one. Without it, the newest:
task_documents. 400 for a revision that is not a whole number from 1, 404 for a task or revision that is not there.
GET /api/board/:taskId
Returns one task with its comments (oldest first) and its ancestors (the chain of parent tasks).
- Path params:
taskId. - Request body: none.
Responses
200 OK:
404 Not Found: no such task:
500 Internal Server Error:
Example
GET /api/board/inbox
The small read behind the Inbox badge: what is unread for this reader, and what needs a person, across every team. The reader is the person a sign-in proxy vouched for, or else one built-in reader. A person new to the proxy starts caught up.
Don’t poll it. Open the event stream with ?activity=1, and read this when an activity event says something moved.
200 OK:
GET /api/board and GET /api/board/:taskId carry the same state as unread: boolean and activity: { seq, kind, at } | null. kind is created, status, edited or comment. activity is null for a task last changed before the board kept this record. Rows from GET /api/board?ready=true carry neither field: that read is for picking work, so use a plain GET /api/board for read state.
POST /api/board/:taskId/read
Mark a task read as of the change the page showed, which is what makes a change that landed since stay unread. A person’s write: it takes the person check. This is a speed bump rather than a boundary, as on comments: any program running as the same user can send the same headers.
Request body:
Responses:
POST /api/board/inbox/read
Mark everything read as of through, or one team’s tasks. A change after through stays unread. The same rule on who may call it as POST /api/board/:taskId/read.
Request body:
Responses:
200 { ok: true }, 400 for a bad body, 403 { error: 'person_only' }.
POST /api/board/:taskId/claim
Claims a todo task for one assignee. The claim succeeds only while the task is todo, unassigned and not dropped, so at most one caller wins: the task moves to in_progress, and every other caller gets 409. A won claim writes a task_claimed event and posts a line to the team’s peer room.
A 409 means another worker holds the task: do not retry it. A task left in_progress by a run that died is released back to todo by the server’s stale-run cleanup, and a normal claim can then take it.
- Path params:
taskId. - Request body:
Responses
400 Bad Request: body failed validation:
200 OK: the claim won; the task is now in_progress and assigned:
404 Not Found: the task does not exist (reason: 'not_found'):
409 Conflict: the task was not in a claimable state (already claimed, dropped, or not todo), it is assigned to a person (person_assigned), or a pause covers it (paused):
500 Internal Server Error:
Example
PATCH /api/board/:taskId
Changes a task’s status, edits its priority, title or description, or both. At least one field is required. The status change follows the status rules (an illegal move is 409 illegal_transition). A move to done is also refused with 409 verification_required when the task’s stored check result is fail, or completed_with_debt with a failing last check. The only way past that is humanOverride: true, and a done with the override writes a verification row to the audit log.
A priority of Urgent is kept only from a request that passes the person check; any other caller stops at High. Changing title or description takes the same check, because they are the brief the task’s next run follows: any other caller gets 403 { "ok": false, "error": "person_only" }, and sent unchanged they change nothing. That check is a speed bump, not a boundary (see Security).
This is the route a person uses (the board and the task drawer), and a person’s move is the final word on the task. These rules hold for a request that passes the person check:
- A move to
doneorcancelledmay carrycompletedAt, the day it really finished. It must fall between the task’s creation and now (up to 5 minutes ahead of the server clock is allowed), else 400invalid_completed_at. Without it the finish time is now. Writing the same finished status again never moves the finish time. - On a person’s main task (
isMainTask: 1), a person can only move it todoneorcancelled, from any open status. Anything else, and any move by a caller that does not pass the person check, answers 409main_task. Either move also cancels every open task under it, at any depth, in the same write, stops their runs, and returns them ascancelledDependents. A move it refuses changes none of them. - A move to
cancelledalso cancels the task’s pending (todo/backlog) dependents, which could otherwise never run, and returns them ascancelledDependents. It frees each of their places under their parent for the Tasks tools’ child cap. - A move to
backlog,todo,blocked,doneorcancelledstops the run working on the task, whether team chat, the task runner or an OpenClaw Routine fire started it, and closes its ledger row as cancelled. A move toin_progressorin_reviewstops nothing. A task moved back totodowhile it was running is started again for its bound agent. - Whoever delegated the task (the
:reflectTo:agent in itssourceDelegationId) is told a person marked it done or cancelled it: through a[Task Update]when the team’s engine is running, else as a mailbox notice read at its next turn. A task a person assigned reports to nobody. - The move is stamped on the task as
personMovedAt. Until a run starts after it, the agent’s own status writes through the tasks MCP tools (update_task_status,block_task,unblock_task) are refused with a tool error that names the column the person chose and tells the agent not to retry, so the run the person overruled cannot put the card back. A run that starts after the move writes as usual.
A task with no stored check result is unchecked, not failing, and moves to
done normally. Most tasks never get a check: only task-runner runs in a git worktree with a non-empty diff, and team-chat work that changed the folder of a team with a work check, are checked (see Verification). Moving a task to todo clears its assignee and check result so it can be claimed again.personMovedAt, stops no run and tells no delegator, cannot change a task a person moved after its latest run started (409 person_moved), and ignores humanOverride, so a failing check still refuses done. Its event records actor: { kind: 'caller' } and no by, and the answer carries byPerson: false. Field edits (priority, title, description) work the same from every caller and write no event.
A status change writes a status_changed event with the actor that made it, and posts A person moved "<title>" to <Status>. (from another caller, A local API call moved ...) to the team’s peer room.
- Path params:
taskId. - Request body (at least one field required):
Responses
400 Bad Request: empty body or failed validation (including completedAt without a move to done or cancelled), or { ok: false, error: 'invalid_completed_at' } for a finish time outside the task’s life:
200 OK: applied; the updated task, and on a move to cancelled the dependents cancelled with it:
404 Not Found: the task does not exist (reason: 'not_found', or the field update found no row):
409 Conflict: the status transition is illegal, the verification gate blocked →done, or (from a caller the person check did not let through) a person moved the task after its latest run started:
500 Internal Server Error:
Example
POST /api/board/:taskId/comments
authorAgentId is read only from a request that passes the person check. From any other caller it is dropped, so a script cannot sign a comment with a teammate’s name.
Adds a comment to a task (discussion or a system note). authorType defaults to agent. The route writes a comment_added event and posts the first 160 characters to the team’s peer room. An unknown taskId is not checked first: the insert fails the database’s foreign key and the route answers 500 (FOREIGN KEY constraint failed).
A user comment is a person’s reply, and only a request that passes the person check can post one: the dashboard’s own page, or a person a sign-in proxy vouched for. The route reads the fetch metadata a browser adds to the page’s requests: Sec-Fetch-Site: same-origin with Sec-Fetch-Mode: cors or same-origin. From any other caller, such as curl or a command an agent runs, a user or system comment is saved as an agent comment and answers with no delivery: it is not delivered as your reply and starts no run. Like any comment, its first 160 characters are still posted to the team room, where the team’s agents can read them. This is a speed bump, not a security boundary: a program running as you can send the same headers, or write Clawboo’s database directly.
After a person’s comment is saved, the route delivers it to the agent the task belongs to: the assignee, or else the agent named in the task’s sourceDelegationId (a task moved back to todo keeps that binding). Nothing is delivered when there is no such agent, or when the task is done, cancelled or dropped.
- A saved wake, always first, except on a
backlogtask and on a run the task runner is driving now. It is folded into the wake already waiting for that agent and task, if one is, and it holds the comment’s id until a run takes it. A task the task runner runs also gets a mailbox note,A person commented on your task "<title>": ..., with the comment’s first 1000 characters: it has no ticket block. - Then by status:
in_progresswith a run working on it: a steer into that run, with comments sent within a second of each other going in as one. How it gets in depends on the runtime (see Choose a runtime). The route waits up to 2.5 seconds for the steer to land, and the steer carries on in the background after that. When it lands whole, that run carries the comment, and it counts as heard when the run ends well; a run that dies gives it back. When it does not land, or does not fit (1,000 characters, with a cut marker that namesget_task), the comment rides the task’s next turn: on team chat work, the agent answers it before the task can bedone.blocked,todo, orin_progresswith no assignee and no run going: the task is started again, as the retry route above does. A task that is nottodomoves there first (with astatus_changedevent whose reason isreply). If every task it depends on isdone, the route adds thesystemcommentStarted again for a person’s reply.and dispatches the task to its agent; otherwise the reply waits with the wake. Atodotask whose reply folded into a wake a run is already on its way for is not dispatched again; a wake that was held, replaying or not a person’s starts it now. While the engine is held, nothing moves or starts, and the reply answersqueued,held.in_review: the reply waits with the wake, and the agent reads it in its next turn, whatever the check answers.backlog: nothing starts, and the agent reads the comment in its ticket block when the task next runs.
todo is refused, is not started again: the reply waits for its next run. A reply that would start the task again in team chat (a blocked or todo task, or a stranded in_progress one) is not delivered when the task is still filed under an archived chat room (not-delivered, room_archived), or under a room that went with its team (no_team). The comment stays saved, and the task is left as it was with nothing written for the reply.
- Path params:
taskId. - Request body:
Responses
400 Bad Request: body failed validation:
200 OK: the created comment:
delivery says where a person’s reply went. agentId is the agent the task belongs to.
For a
finished reply, the dashboard offers Send as a follow-up task, which calls POST /api/board (above) with title: "Follow up: <title>", the reply as description, the same teamId and assigneeAgentId, and the finished task as parentTaskId.
500 Internal Server Error:
Example
PUT /api/board/:taskId/labels
Replaces the task’s labels with this set, all from its own team. A person’s call: a request that does not pass the person check gets 403 person_only. That check is a speed bump, not a boundary. The change goes on the audit feed as a board event, with its actor and the person a sign-in proxy vouched for.
- Path params:
taskId. - Request body:
{ labelIds: string[] }. At most 10.
Responses
200 OK: { labels: Array<{ id: string; name: string }> }.
400 Bad Request: the body failed validation.
403 Forbidden: { "error": "person_only" }.
404 Not Found: { "error": "not_found" }, no such task.
409 Conflict: { "error": "label_not_in_team" } (a label of another team, or any label on a task with no team) or { "error": "too_many" }.
POST /api/board/:taskId/executions
Opens a row in the task’s run ledger, after a successful claim. The server reads the ledger after a restart to find runs that died: a worker that starts work must open a row here and close it with the PATCH below. A row left open by a crash is marked failed and its task released. A new row writes an execution_started event.
A new run is what ends a person’s hold on a card (see PATCH above), so while a person’s move stands, a caller that does not pass the person check gets 409 { "ok": false, "error": "person_moved" } and no row is opened.
- Path params:
taskId. - Request body:
Responses
400 Bad Request: body failed validation:
404 Not Found: the task does not exist:
200 OK: the created execution row (starts in status: 'running'):
500 Internal Server Error:
Example
PATCH /api/board/executions/:execId
Closes a run in the ledger with its outcome, and optionally its tokens and cost. The route writes an execution_completed event carrying the run’s taskId, teamId, agentId and runtime, so it pairs with the execution_started event. A closed row never changes again, so only a running row can be closed: an unknown execId, or one already closed elsewhere, closes nothing and answers 404 without an event.
- Path params:
execId. - Request body:
null fails validation with 400. A costUsd sent without a costSource is stored with a null source, which the board counts as an estimate. A close that records a cost also refreshes the task’s costUsd, the sum of its rows.
Responses
400 Bad Request: body failed validation:
200 OK: the execution was closed:
404 Not Found: no still-running execution row matched execId, either because the id is unknown or because the row is already terminal (most often the stale sweep closed it as timed_out). Nothing was closed and no event was appended, and this 404 is data rather than a transient error to retry:
500 Internal Server Error:
Example
GET /api/board/:taskId/executions
Lists every run in the task’s ledger, oldest first.
- Path params:
taskId. - Request body: none.
Responses
200 OK: the ledger (executions[] is DbExecutionProcess[], shape as in POST .../executions):
500 Internal Server Error:
Example
POST /api/board/:taskId/deps
Makes taskId wait for dependsOnTaskId: it is not ready until the other task is done. A plan is a chain of these links, and the team’s engine starts the next step when the one before it finishes. Both tasks must exist. A new link writes a dep_linked event and posts a line to the team’s peer room.
- Path params:
taskId(the dependent). - Request body:
Responses
400 Bad Request: body failed validation:
404 Not Found: either the task or the blocker does not exist:
200 OK: the edge was linked (duplicate edges are ignored):
409 Conflict: the edge would close a direct or transitive dependency cycle. A cycle can never resolve, so the plan is unworkable rather than the server being at fault:
500 Internal Server Error:
Example
POST /api/board/:taskId/cancel-dependents
Cancels the tasks still waiting (todo or backlog) behind a failed task, directly or further down the chain. A failed task never becomes done, so those tasks could never run; cancelling them shows the stall instead of leaving cards that never become ready. Tasks in any other status (in_progress, in_review, blocked, done or cancelled) are left alone. Each cancelled task writes a status_changed event with reason: 'blocker_failed', and the response lists them so the caller can tell the team lead.
- Path params:
taskId(the failed blocker). - Request body: none.
Responses
404 Not Found: the task does not exist:
200 OK: the cancelled dependents (id + title only; may be an empty array):
500 Internal Server Error:
Example
POST /api/board/:taskId/workspace
Creates a git worktree and a clawboo/task-<id> branch for a task that changes files, writes the task files into it, and records the worktree and branch on the task. The task files are TASK.md, task-progress.md, DECISIONS.json, init.sh and VERIFICATION.md (plus AGENT_HANDOFF.json once someone writes a handoff); the other workspace routes read them. The worktree lives outside your repo, at <work folder>/worktrees/<repo hash>/<taskId> (see The work folder), so it never shows up in the repo’s own git status. A worktree keeps file changes apart; it is not a sandbox (see What agents can do).
The task kind decides whether a worktree is made: code (the default) and any unknown kind get one; research and review are refused with 422. Asking again for a task that already has a live worktree reuses it and returns the path the task records for it.
- Path params:
taskId. - Request body:
Responses
400 Bad Request: body failed validation:
404 Not Found: the task does not exist (reason: 'not_found'):
422 Unprocessable Entity: the task kind gets no worktree (research or review); it runs in the task’s own folder:
409 Conflict: a folder is already at the task’s worktree path and replacing it could lose work, because it has uncommitted changes or git cannot read it. The folder is left as it is:
200 OK: the worktree was provisioned (or an existing one reused):
500 Internal Server Error:
Example
GET /api/board/:taskId/workspace
Reads the task’s workspace row and the state to resume from, rebuilt only from the worktree’s task files (AGENT_HANDOFF.json, else task-progress.md and init.sh): no chat history and no board state. A different runtime, or a person, can pick the task up from this alone.
- Path params:
taskId. - Request body: none.
Responses
404 Not Found: no workspace row for the task (or it has no recorded worktree path):
200 OK: the workspace, the resume state and the parsed handoff (resume and handoff are null when the worktree is paused or no handoff was written):
Example
PATCH /api/board/:taskId/workspace
Pauses or completes a task’s worktree: the checkout the task records, which has to be the task’s folder under the work folder’s worktrees/<repo hash>/, under <clawboo home>/worktrees/<repo hash>/ (where older versions made them), or where the work folder move kept it (see The work folder). A recorded path anywhere else answers 500 with Error: worktree path does not belong to task <taskId>: <path>, and nothing is removed.
pause: commits any uncommitted work, removes the worktree and keeps the branch. The workspace staysactiveand can be resumed.completewith an empty diff: removes the worktree and branch and moves the task todone. A task intodo(released by a pause, or never claimed) moves throughin_progressfirst; ablockedtask staysblocked. There is nothing to check, so the check is skipped. The task files do not count toward the diff, so a run that only updated its own progress or handoff is still empty.completewith a non-empty diff: moves the task toin_reviewand runs the check, throughin_progresswhen it is intodo. Only apassmoves it todone. Afailwith attempts left moves it back toin_progress. Afailon the last attempt, orcompleted_with_debt, moves it toblockedwith a system comment and a mailbox notice to whoever delegated it. A repeatcompleteon ablockedtask does not run the check again; it returns the current status withverified: 'fail'.
VERIFY_CMD in the worktree’s init.sh (else the Verify: line in VERIFICATION.md). Without a team command the task files start with a placeholder command, which counts as no command, so the check fails until a real one is set. If a person moves the task to done or cancelled while the check runs, their move stands and the result is only recorded. See Verification.
complete takes the person check, because it moves the card and on an empty diff can pass a failing check: any other caller gets 403 person_only and nothing changes. A move it makes writes a status_changed event with reason workspace_complete and the actor, except a move to blocked, which writes its own. pause moves no card and takes no check.
- Path params:
taskId. - Request body:
Responses
400 Bad Request: body failed validation:
404 Not Found: no workspace row (or it has no worktree path / branch):
200 OK (pause): committed-or-not + the resulting HEAD sha:
200 OK (complete): the diff outcome, the resulting task status, and (when the gate ran on a dirty diff) the verification verdict:
500 Internal Server Error:
Example
POST /api/board/:taskId/workspace/handoff
Writes AGENT_HANDOFF.json into the task’s worktree: structured notes on what was done, what is broken and what to do next, so a different runtime or a person can pick the task up. When timestamp is left out, the server fills in the current ISO-8601 time.
- Path params:
taskId. - Request body (
timestampdefaulted server-side):
Responses
400 Bad Request: the handoff failed validation:
404 Not Found: no workspace row (or it has no worktree path):
200 OK: the handoff was written:
500 Internal Server Error:
Example
GET /api/board/:taskId/workspace/detail
What the task drawer’s Files section shows for a worktree: the contents of the task files that exist (TASK.md, task-progress.md, DECISIONS.json, init.sh, VERIFICATION.md, AGENT_HANDOFF.json), plus the unified diff and diff stats against the starting commit, with the task files left out of the diff. The files are read the way the workspace file view reads one, up to 256 KB each, so a task file that is a symbolic link, or that is not text, is left out, and a longer one holds only its first 256 KB and is named in sorFilesTruncated.
- Path params:
taskId. - Request body: none.
Responses
404 Not Found: no task with that id:
200 OK with ok: false: the task exists but has no checkout of its own (no workspace row, or one with no worktree path). Most tasks never get one, so this is the ordinary answer for them. taskFolder is the task’s own folder, where its runs start instead, with onDisk: false until the task’s first run makes it and holdsFiles: false while nothing is in it. Read its files with the task folder file view:
200 OK: the task files and the diff (diffStat and diff are empty when the worktree is paused or git is unavailable):
500 Internal Server Error:
Example
The workspace file view
Four read-only routes behind an agent’s Computer tab and the task drawer’s Files section. They serve a task’s worktree: one directory level, one file, one file’s diff, and the git status behind the change badges. Nothing here writes. The worktree path comes from the stored workspace row, never from the request. Every relative path is kept inside the worktree in three ways: absolute paths and.. segments are refused; the resolved path must sit inside the root (so a sibling such as <root>-evil cannot pass as <root>); and symlinks are refused outright, with the path checked again after resolving any symlinked parent folder. The agent can change the worktree while it is read, so a file is opened without following a link, and checked again after the open: its path must still resolve to itself and name the same file, with one name. A file or folder swapped for a link after the first check is refused too. On Linux the check after the open also asks the kernel where the open file is, which a folder swapped back and forth during the check cannot fool; on macOS and Windows that last case is a race the server can lose. A file with more than one hard link is refused as well, since a hard link can give a file outside the worktree a name inside it; a git checkout never makes one, though a package manager’s store can. Backslashes, control characters and paths over 1024 characters are refused too. A refused path answers 400 { "ok": false, "error": "<what is wrong>" }.
When the workspace itself cannot be read, all four answer { "ok": false, "error": "<message>", "reason": "<reason>" }:
unreadable is not a 404 on purpose: a client that read a git failure as “no workspace” would show a changed worktree as clean.
GET /api/board/:taskId/workspace/tree
One directory level, for a tree that expands on demand. .git, symlinks and special files are left out; folders sort before files, then by name, ignoring case.
- Query:
dir(relative to the worktree; empty or left out lists the root). 200 OK:{ ok, dir, entries: [{ name, kind: "file" | "dir", size? }], truncated }. Only files carrysize. At most 500 entries;truncatedsays the limit was hit.
GET /api/board/:taskId/workspace/file
One file’s contents, up to 256 KB.
- Query:
path(relative to the worktree). 200 OK(text):{ ok, path, binary: false, size, content, truncated }. A cut falls on a character boundary, so a truncated file never ends in a broken character.200 OK(binary):{ ok, path, binary: true, size }. A NUL byte in the first 8 KB marks the file as binary, and no bytes are returned.
GET /api/board/:taskId/workspace/file-diff
The unified diff for one file against the task’s starting commit.
- Query:
path(relative to the worktree). A folder is refused with 400Not a file., since a git path match would otherwise return everything under it. 200 OK:{ ok, path, diff, truncated }, capped at 1 MB. The diff is empty for an untracked file; show the file’s contents instead.
GET /api/board/:taskId/workspace/status
git status --porcelain -z --untracked-files=all for the worktree, parsed.
200 OK:{ ok, branch, entries: [{ path, x, y, origPath? }], truncated }.xis the index column andythe worktree column;origPathis the source of a rename or copy. At most 2000 entries.
Example
The task folder file view
Two read-only routes for a task with no worktree, behind the task drawer’s Files section and the task folders on an agent’s Computer tab. They serve the task’s own folder,<team folder>/tasks/<task id>: one directory level and one file. The folder comes from the task’s row (its team and id), never from the request. Both take the same dir and path query values, keep every path inside the folder by the same rules, and answer with the same shapes as the workspace file view. The folder is not a git checkout, so there is no status or diff. Nothing here writes.
A refused path, such as an absolute path, a .. segment or a link inside the folder, answers 400 { "ok": false, "error": "<what is wrong>" }. When the folder itself cannot be read, both answer { "ok": false, "error": "<message>", "reason": "<reason>" }:
GET /api/board/:taskId/folder/tree
One directory level of the task’s folder, as workspace/tree lists one of a worktree.
- Query:
dir(relative to the task’s folder; empty or left out lists the root). 200 OK:{ ok, dir, entries: [{ name, kind: "file" | "dir", size? }], truncated }.
GET /api/board/:taskId/folder/file
One file’s contents, up to 256 KB, as workspace/file reads one from a worktree.
- Query:
path(relative to the task’s folder). 200 OK:{ ok, path, binary: false, size, content, truncated }for text, or{ ok, path, binary: true, size }.
Example
GET /api/board/:taskId/preview and GET /api/board/:taskId/preview/<path>
Serves the files in a task’s worktree, or in the task’s own folder when it has no worktree, as a static website, so the task drawer’s Preview can show the page an agent built. It only serves files: it never runs a build or a dev server. The drawer checks for a preview every 10 seconds while it is open.
GET /api/board/:taskId/previewandGET /api/board/:taskId/preview/<path>serve the same tree. A folder (including the bare route) serves itsindex.html. A folder URL without a trailing slash answers302to the same URL with a/added (the base path and query are kept), so the page’s relative links resolve.- Paths follow the same rules as the workspace file view: no
.., symlinks, hard-linked files, backslashes or control characters, and at most 1024 characters. Leading slashes are dropped, sopreview//index.htmlis theindex.htmlat the top of the worktree or task folder, never a path from the root of the disk. Content-Typecomes from a fixed list:html/htm,css,js/mjs,json/map,txtandmd(astext/plain),svg,png,jpg/jpeg,gif,webp,avif,ico,woff/woff2,ttf,otf,mp4,webm,wasm. Anything else is sent asapplication/octet-stream, which a browser downloads rather than runs.- Every file is sent with
Content-Length,Cache-Control: no-storeandX-Content-Type-Options: nosniff, and streamed. - Every response, redirects and errors included, carries
Content-Security-Policy: sandbox allow-same-origin. - The routes sit under
/api, so the same-origin guard and the access gate apply, and the dashboard’s access cookie reaches the preview frame.
allow-same-origin only, and the Content-Security-Policy header applies the same sandbox when the Open link, or anyone with the URL, loads the page in a tab of its own. Styles and images load, and a script-driven page appears as its static shell. allow-same-origin stays because without it the page’s own requests for its styles and images count as cross-site, and the same-origin guard refuses them.
Responses
200 OK: the file’s bytes.
302 Found: a folder requested without a trailing slash.
400 Bad Request: a refused path, or a missing file. The message names the problem, for example:
404 Not Found: { "ok": false, "error": "<message>" }, where the message is workspace not_found, workspace gone or workspace unreadable (no usable worktree or task folder), No index.html in that directory., or Not a file.
413 Payload Too Large: a file over 8 MB: { "ok": false, "error": "That file is too large to preview." }
500 Internal Server Error: { "error": "<message>" }, including when a file that is there cannot be opened (no permission, no file descriptors left), or preview read failed when reading it fails partway.
Example
Error envelope
Most error bodies are{ "error": "<message>" }. The exceptions:
- Validation
400s adddetails(the zodflatten()output):{ "error": "invalid body", "details": {...} }, orinvalid handoffon the handoff route. { "ok": false, "error": "<reason>" }comes from: the claim (not_found,conflict); a status change onPATCH /api/board/:taskId(not_found,illegal_transition,verification_required, andinvalid_completed_atas a400); every retry and assign failure (task not found,agentId required,not_retryable,no_team,unassigned,agent_not_in_team,not_assignable,room_archived); the dependency cycle (409 task_dependency_cycle); the provision route (task not found, andno_isolationwithisolation); and the pause, complete and handoff404s (workspace not found).- The workspace file view adds
reasonto its misses and answers a refused path with{ "ok": false, "error": "<message>" }. - The preview routes answer
{ "ok": false, "error": "<message>" }on400,404and413. GET /api/board/:taskId/workspaceanswers a missing workspace with a bare{ "error": "workspace not found" }./workspace/detailanswers a task without one with200and{ "ok": false, "reason": "no_workspace" }, and an unknown task with404and{ "error": "task not found" }.
taskId on a comment, or an unknown parentTaskId on a create, is a 500 from the database’s foreign key, not a 404.
Related
- The board: statuses, claims, dependencies and how stuck tasks are recovered.
- Worktrees and handoff: the task files and
AGENT_HANDOFF.jsonacross runtimes. - Verification: which tasks are checked, and what
completed_with_debtmeans. - Runtimes API:
POST /api/runtimes/:id/runclaims one of these tasks and runs it. - Database schema: the
tasks,task_deps,task_comments,workspacesandexecution_processestables.