home.goals (see System) says the engine has these routes. The typed client is home.ts in @clawboo/control-client.
Every write here is a person’s. A request that may not act as the person (see the person check) gets 403 with "error": "person_only". Agents reach Home only through the Tasks MCP tools, and only to report a KPI value, suggest a KPI, write a page or draft a goal update. No route or tool lets an agent define a KPI, change a target, set a goal’s health or publish an update.
Every route is on the general rate limit, and the two settings writes also on the sensitive one. Request bodies are JSON. Add the access cookie to each curl example (see Authentication). Times are epoch milliseconds.
Where each number comes from
Routes
A goal, update, KPI or page of another team answers
404, the same as one that does not exist. A team that does not exist answers 404 with "error": "team_not_found". With roles enforced, reads need see, writes need work, the settings write needs an owner or operator, and turning on weekly updates needs setup. A guest reaches only the teams their token lists, and the all-teams read shows only those.
Errors
A refused write answers{ "ok": false, "error": "<code>" }:
too_many is a limit: 100 goals and 60 KPIs a team (not counting archived ones), 10 suggestions waiting at once, 5 drafts waiting on one goal (each agent holds at most one, rewritten in place), and 100 values a KPI takes in a rolling day. Pages limit agents only, so a person is never stopped from editing or reverting one: an agent may not start a page once the team has 300 (not counting archived ones), nor more than 10 new pages a day, nor add a revision to a page that has 200, nor more than 6 revisions to one page in an hour. lead_cannot_write: see Settings and weekly updates.
GET /api/home
One team’s Home with?teamId=<id>, or all teams with no team (or teamId=all).
{ "scope": "team", "home": TeamHome } or { "scope": "all", "home": AllTeamsHome }:
recentFiles lists up to 8 files from the top of the folders of the team’s 8 most recently changed tasks (<team folder>/tasks/<task id>), the most recently modified first. Each folder’s first 40 entries in name order (folders first) are read, so a folder with more entries can hold a newer file than the ones listed. Open one with GET /api/board/:taskId/folder/file?path=. A folder that is gone or unreadable is skipped. Worktree checkouts are not listed.
The status line
facts, for example “2 requests in flight, 1 needs you, 3 done this week, $12 of $60 spent.” A team can turn on a line its lead writes (settings). Each ask is a model call, so it is off until a person turns it on, and the asks keep to limits that waste none. Every 15 minutes Clawboo looks at the teams that turned it on and asks the lead for a line in the team chat (it shows as “Routine · Home status line”) only when the team’s board moved past every point already seen: where it stood when the line was turned on, at the last ask, and at the last line. An untouched board is never asked about. Asks and lines share one clock: at most one every 6 hours, counting both, and at most 4 asks in a rolling day. The lead answers with the write_home_summary tool, and a line that answers the ask always lands. A line the lead writes unasked keeps to the same board and clock rules. A lead that cannot hold the tool (see leadCannotWriteReason in settings) is never asked, even if the lead changed after the line was turned on. An ask that fails to post (a pause covers the team, or the engine is down) is taken back, so the next pass asks again instead of waiting out the clock. A written line older than a day gives way to the computed one.
Goals
goalId, else the nearest goal up its parent chain, which is its request’s when nothing between names another. Every create copies the parent’s goal down when the task is made, and work filed before its request had a goal is read as its request’s. A task only serves a goal of its own team: a goal of another team counts as none.
GET .../goalslists the team’s goals that are not archived, whatever their status (active, done and dropped), as{ "goals": GoalSummary[] };?includeArchived=trueadds archived ones. The team’s Home (GET /api/home) shows only the active ones.POST .../goalstakes{ title, description?, parentGoalId?, owner?, targetDate?, updateCadenceDays? }and answers{ "goal": TeamGoal }.PATCH .../goals/:goalIdtakes any of those fields andstatus. A parent must be a goal of the same team that is not archived and has no parent itself; a goal with child goals cannot take a parent.DELETE .../goals/:goalIdarchives the goal. Its tasks keep their link; its child goals lose their parent; its open drafts are discarded, so they leave Needs you.POST .../goals/:goalId/healthtakes{ "health": "on_track" | "at_risk" | "off_track" | null }. Each change is recorded.POST .../goals/reordertakes{ "goalIds": string[] }: those first, in that order; the rest keep their order after them.
GET .../goals/:goalId answers { "goal": GoalDetail }:
Linking tasks to goals
POST /api/board and PATCH /api/board/:taskId take goalId: a goal of the task’s own team, or null for none. Another team’s goal answers 400 with "error": "goal_other_team". Changing a task’s goal is a person’s write (on POST, a goalId from a caller that is not a person is ignored and the task takes its parent’s goal). null takes the task off every goal, its request’s included, and the work under it with it. When a task’s goal changes, the work under it that still carried the old goal moves to the new one; work a person put on another goal stays there. A person’s team chat message (POST /api/teams/:id/chat) can carry goalId too: the request’s main task, and the work filed under it, serve that goal. Board task rows (GET /api/board, GET /api/board/:taskId, and the task a create or patch returns) and board change frames carry the stored goalId and the goal the task counts toward: effectiveGoalId, with goalLinkedVia own, request or parent (the goal page’s linkedVia). A subtask or hand-off made under a request that has a goal stores that goal as its goalId. Work filed before its request had a goal keeps a null goalId and has effectiveGoalId set through the request, so a goal chip and a “No goal” filter read effectiveGoalId.
Goal updates
draft_goal_update. Each agent holds at most one open draft on a goal: drafting again rewrites it in place (its words, health, run and time), so the table does not grow with each draft. Publishing an update that names a health sets the goal’s health, recorded as set by the person who published it.
POST .../goals/:goalId/updatestakes{ body, health? }: a person’s own update, published at once. Answers{ update, goal }; an archived goal answers409 goal_archived.POST .../updates/:updateId/publishtakes{ body?, health? }to edit before publishing. Answers{ update, goal }; a draft that is not a draft any more answers409 not_draft, and a draft on an archived goal409 goal_archived.POST .../updates/:updateId/discardanswers{ update }.
KPIs
stale when its value is older than staleAfterHours, and missing when there is no value yet. A computed reading is always ok, with asOf the time of the read. An agent or person reading uses only values from the KPI’s current source, by who reported them: a person’s values for a person KPI, an agent’s for an agent one. So after its source changes, a KPI reads missing until the new source reports. Its value history keeps every value.
GET .../kpisanswers{ "kpis": KpiTile[] }: active and suggested (?includeArchived=trueadds archived).POST .../kpistakes{ name, source, unit?, direction?, target?, period?, metric?, goalId?, reporterAgentId?, staleAfterHours? }. A computed KPI needs ametric; a reporter must be an agent on the team. Answers{ "kpi": KpiTile }.PATCH .../kpis/:kpiIdtakes the same fields.DELETEarchives it.POST .../kpis/:kpiId/accepttakes the same fields as edits and makes a suggestion active;dismissarchives it.POST .../kpis/:kpiId/valuestakes{ value, asOf?, note?, sourceUrl? }, only for an active KPI whose source isperson. A source link must start withhttp://orhttps://. Answers{ value, kpi }.GET .../kpis/:kpiId/values?limit=answers{ "values": KpiValue[] }, newest first.limitis a whole number from 1 to 1,000 (default 100); anything else answers400 invalid.
Computed metrics
Worked out on read, for the KPI’s team and period. Three read the state now and ignore the period.Pages
write_page, inside the agent limits under Errors, and a person can always revert its revision: no limit applies to a person’s edits or reverts.
GET .../pagesanswers{ "pages": TeamPage[] }(?goalId=for one goal’s,?includeArchived=true).POST .../pagestakes{ title, body?, goalId?, pinned? }and answers{ "page": TeamPage & { body } }.GET .../pages/:pageIdanswers{ "page": TeamPage & { body } }.PATCH .../pages/:pageIdtakes{ title?, body?, goalId? }. A new title or body makes a new revision; a goal change alone makes none. An archived page answers409 archived.GET .../pages/:pageId/revisions?before=&limit=answers{ revisions: TeamPageRevisionMeta[], nextBefore: number | null }: revisions newest first without their words, up tolimit(default 50, at most 200) numbered belowbefore. PassnextBeforeasbeforefor the next page; it is null on the last one.GET .../pages/:pageId/revisions/:revisionanswers{ "revision": TeamPageRevision }with its words, or404 revision_not_found.POST .../pages/:pageId/reverttakes{ "revision": number }and makes a new revision with that one’s title and body.POST .../pages/:pageId/pintakes{ "pinned": boolean }.DELETEarchives the page and unpins it.
Settings and weekly updates
GET /api/home/teams/:teamId/settings
Answers{ "settings": { leadWritesStatus: boolean, leadCanWriteStatus: boolean, leadCannotWriteReason: string | null, weeklyUpdatesRoutineId: string | null } }. leadCanWriteStatus is false when the team’s lead cannot write the line, because it is never offered write_home_summary, and leadCannotWriteReason says why (null when it can):
Codex, Claude Code and Hermes leads get a signed Tasks session bound to them on every team run, so they can write it.
PUT /api/home/teams/:teamId/settings
Takes{ "leadWritesStatus": boolean }. Turns the lead-written status line on or off for the team; each change is in the audit log. Turning it on for a team whose lead cannot write it answers 409 with "error": "lead_cannot_write". Turning it on records where the board stands, and the first ask waits for the board to move past it.
POST /api/home/teams/:teamId/weekly-updates
Makes a normal team routine, “Weekly goal updates”, on Mondays at 09:00 in the routines’ time zone. It asks the team’s lead to calldraft_goal_update for each active goal. The drafts wait on Home and count in Needs you. Answers { routineId, settings, created }; calling it again returns the routine it made (created: false) while that routine exists. Pause, change or delete it from Routines like any other.