teams table. An agent’s team is the nullable agents.teamId column: a team has many agents, and an agent belongs to at most one team. A team’s chat rooms are the rooms and room_members tables. The intro flags, team rules and verify command are not tables; they are JSON values in the settings table under team-onboarding:<teamId>, team-rules:<teamId> and team-verify-command:<teamId>. The peer-chat room is the team_chat table, the one the TeamChat MCP server writes.
DELETE /api/teams/:id first stops the team’s chats and their runs, and cancels its open requests with the work under them. Its other tasks stay as rows no engine, wake, rerun or routine will start. An agent routine’s teamId becomes null with its agent’s, so it keeps its schedule and files its tasks with no team. A team routine keeps the team’s id and fails on its next run. It keeps the team’s agents: it sets their teamId to null and removes the team’s rules, verify command, intro flags, General clear time and resume pointers, and the team’s folder with its files, its task folders included. The dashboard’s Delete with agents first deletes each agent with DELETE /api/agents/:agentId (see the Agents API) and then deletes the team, so a REST caller that wants the same result deletes the agents itself.Two different things on this page are called rooms. A team’s chat rooms (
/api/teams/:id/rooms, and the roomId the chat routes take) are conversations inside the team chat, each with some of the team’s members. The team’s main chat, General, is the default: it has no room row, and leaving roomId out means General. The peer-chat room (/api/team-chat, whose roomId is team:<teamId>) is where the TeamChat MCP server’s posts go. Its id is never a chat room id, and the dashboard does not show it.PUT /api/team-verify-command/:teamId, PUT /api/team-plan-approval/:teamId and PUT /api/team-agent-wakes/:teamId, which are also on the sensitive tier (60 a minute). Add the access cookie to each curl example (see Authentication). Most routes name the team :id (the single-room routes add :roomId); the team-rules and team-verify-command routes name it :teamId. Both are the team id.
Routes
GET /api/teams
Lists every team with a computed agentCount (a COUNT(*) subquery over agents.team_id). Also returns the full agent→team assignment list so a client can patch its fleet store after hydration. Archived teams are excluded unless includeArchived=true. Each team also says whether the server orchestrates it (serverOrchestrated) and when its General chat was last cleared (chatClearedAt); a room’s clear time is on the room (see GET /api/teams/:id/rooms).
- Path params: none.
- Query params:
- Request body: none.
Responses
200 OK: the team list plus assignments:
500 Internal Server Error: any DB failure:
Example
GET /api/teams/member-roles
The one-line role each live team member states in its SOUL.md, for the board’s New task dialog to suggest who fits a sentence (see Giving an agent a task). Roles are read with the same reader as the team lead’s roster: a - **Role**: bullet, else the first Role or Mission section, else the intro paragraph. An agent with no role there is left out: OpenClaw agents (their files live on the Gateway), agents with no persona or the shipped default prompt, teamless agents and archived agents.
- Path params: none.
- Request body: none.
Responses
200 OK: roles keyed by agent id:
500 Internal Server Error: a DB failure:
Example
POST /api/teams
Creates a team. The server makes a random UUID for the id unless the body sends a valid UUID id; the create-team UI seeds a client-side id so the Boo color-palette preview matches the deployed team (per-team color rotation is seeded off the team id). name, icon, and color are required; everything else is optional and stored as supplied (null when omitted).
- Path/query params: none.
- Request body:
Responses
400 Bad Request: body is missing or not an object:
400 Bad Request: a required field is missing:
200 OK: the created team (note: 200, not 201):
500 Internal Server Error: the insert failed:
Example
PATCH /api/teams/:id
Changing isArchived or leaderAgentId is a person’s call: a caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. The other fields, and an isArchived that changes nothing, are open.
Partially updates a team. Only the fields present in the body are written; updatedAt is always refreshed. isArchived is coerced to 0 or 1 from the body’s truthiness. Returns the full updated row (including a recomputed agentCount).
- Path params:
id(team id). - Request body (all optional):
Responses
400 Bad Request: the :id segment is missing:
400 Bad Request: the body is missing or not an object:
404 Not Found: no team with that id:
200 OK: the updated team:
500 Internal Server Error: the update failed:
Example
DELETE /api/teams/:id
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
It stops the team’s runs and closes its open requests in the person’s name, so each delete goes in the audit log (delete_team, with who did it).
Deletes the team and keeps its agents. In one call it (1) sets teamId = null on every agent in the team, (2) deletes these team-scoped settings rows: team-rules:<teamId>, team-onboarding:<teamId>, team-verify-command:<teamId>, General’s clear time team-chat-cleared:<teamId>, and every member’s native resume pointer for the team and for each of its rooms, (3) deletes the team row, and (4) when a team row was deleted, removes the team’s folder, <work folder>/teams/<teamId>, with every file in it, including each task’s own folder under tasks/, and the link the work folder move left at <CLAWBOO_HOME>/workspaces/<teamId>, if there is one. The boo_zero_team_briefs and rooms tables FK-cascade on the team delete (room memberships go with their rooms), so per-team briefs and chat rooms clean themselves. The team’s board tasks, chat messages and peer-chat posts are not deleted, and neither are the team-server-orchestrated:<teamId> setting and each room’s clear time.
- Path params:
id(team id). - Request body: none.
Responses
400 Bad Request: the :id segment is missing:
200 OK: the team was deleted and its agents orphaned. folderRemoved is false when the folder could not be removed, or when no team had that id:
500 Internal Server Error: a DB failure:
The route does not answer 404 for an unknown team id: the updates and the delete match nothing, so it still returns
{ ok: true, folderRemoved: false } and touches no folder.Example
POST /api/teams/:id/agents
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Assigns an agent to the team. This is an upsert: if the agent row does not exist it is created (with status: 'idle' and gatewayId = agentId); if it exists, only its teamId and updatedAt are set. The optional agentName is used as the display name when creating a new row (it defaults to the agentId).
Because it sets only the team column, an existing agent’s unstarted tasks, routines, room memberships and resume pointers stay on its old team. To move an agent between teams, use POST /api/agents/:agentId/move on the Agents API, which moves them in one step and refuses Boo Zero, a team’s Leader and an agent with a task in progress.
Two more behaviors:
- An OpenClaw agent that was deleted while its Gateway was down, and is not yet deleted in the Gateway, cannot be assigned: the route answers 409, because the upsert would bring its row back.
- When the agent runs on Clawboo Native, the route creates the default native Boo Zero before it answers, if none exists yet and a native provider is set up. So Boo Zero exists by the time the response arrives.
-
Path params:
id(team id). - Request body:
Responses
400 Bad Request: the :id segment is missing:
400 Bad Request: the body is missing/non-object or has no agentId:
409 Conflict: the agent is an OpenClaw agent whose delete is still pending (it was deleted while the Gateway was down):
200 OK: the agent was assigned (created or updated):
500 Internal Server Error: the upsert failed. The route does not check the team first, so an unknown team id lands here (a FOREIGN KEY constraint failed message), not on a 404:
Example
DELETE /api/teams/:id/agents/:agentId
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Removes an agent from a team by setting its teamId to null. The agent row is not deleted.
- Path params:
id(team id),agentId(the agent to orphan). - Request body: none.
Responses
400 Bad Request: the :agentId segment is missing:
404 Not Found: the agent is not on this team:
200 OK: the agent’s teamId was cleared:
500 Internal Server Error: the update failed:
Example
GET /api/teams/:id/rooms
Lists the team’s chat rooms in creation order, oldest first. Archived rooms (the ones deleted in the dashboard) are not listed, and neither is General: the team’s main chat is the default and has no row. An unknown team id is not a 404; it returns an empty list. The sidebar applies its own order (pinned rooms first, most recently pinned on top, then newest first).
- Path params:
id(team id). - Request body: none.
Responses
400 Bad Request: the :id segment is missing:
200 OK: the team’s active rooms:
500 Internal Server Error: a DB failure:
memberIds is the stored membership. The room’s live roster, the agents its chat lists and routes to, is that list minus any agent that has since been archived or moved to another team (an agent row that is deleted leaves the list by itself), plus Boo Zero, which presides over every room without being stored as a member.Example
POST /api/teams/:id/rooms
Creates a chat room from a name and a subset of the team’s members, and returns it with 201. The name has its whitespace collapsed, is trimmed, and is cut to 80 characters. Duplicate member ids count once. Every member must be an active (not archived) agent of this team. Boo Zero needs no membership, because it presides over every room; the default Boo Zero has no team, so its id is refused as a member like any other agent outside the team. A new room starts unpinned and never cleared.
- Path params:
id(team id). - Request body:
Responses
The checks run in this order:400 Bad Request: the :id segment is missing:
400 Bad Request: name is missing, not a string, or empty once its whitespace is collapsed:
404 Not Found: no team with that id:
400 Bad Request: memberIds is missing, not an array, or holds anything other than non-empty strings:
400 Bad Request: memberIds is an empty array:
400 Bad Request: one or more ids are not active agents of this team (the message lists them, comma-separated):
201 Created: the new room:
500 Internal Server Error: a DB failure:
Example
PATCH /api/teams/:id/rooms/:roomId
Changes a room: rename it, replace or add to its members, or pin or unpin it, in any combination. Every field you send is validated before anything is written. memberIds replaces the whole member set; the members you keep keep their place in the roster order. addMemberIds adds agents and leaves the current members in place, so two adds sent at the same time both land; the dashboard uses it when an agent made on a room’s graph joins that room. Send one or the other, not both. A member you remove finishes the turn it is already running, and the room’s next turns no longer list or route to it (the roster is read fresh on every turn). Pinning stamps pinnedAt with the current time, even on a room that is already pinned, which moves it to the top of the pinned rooms; unpinning clears it.
- Path params:
id(team id),roomId(the room). - Request body (at least one field):
Responses
The checks run in this order:400 Bad Request: a path segment is missing:
400 Bad Request: pinned is present but not a boolean:
400 Bad Request: both memberIds and addMemberIds are present:
400 Bad Request: the body has none of name, memberIds, addMemberIds, or pinned:
404 Not Found: no active room with that id in this team (an archived room, or another team’s room, is not found):
400 Bad Request: name is present but not a string, or empty once its whitespace is collapsed:
400 Bad Request: memberIds is present but invalid, with the same three errors as POST /api/teams/:id/rooms: memberIds must be an array of agent ids, a room needs at least one member, or not active members of this team: <ids>.
400 Bad Request: addMemberIds is present but invalid: addMemberIds must be an array of agent ids, addMemberIds must name at least one agent, or not active members of this team: <ids>.
200 OK: the updated room:
500 Internal Server Error: a DB failure:
Example
DELETE /api/teams/:id/rooms/:roomId
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
It stops the room’s runs, as the Stop button does, so archiving a room goes in the audit log (archive_room, with who did it).
Archives the room; nothing is deleted. In one call it sets the room’s archived_at (from then on nothing routes work to it), drops the room’s resume pointers (native-team-session:<agentId>:<teamId>:room:<roomId>) so no agent resumes the archived conversation, stops the room’s work and waits for that Stop to be written (a clean Stop, as POST /api/teams/:id/chat/stop does for this roomId: claimed tasks are released to todo, queued ones are marked stopped, and nothing is reported as a failure), and then moves the room’s unfinished tasks to General. The conversation stays in chat_messages under the room’s session keys and the room leaves GET /api/teams/:id/rooms.
The moved tasks stay stopped, as a Stop leaves them. A task still running with no engine to stop it (after a restart the room’s engine may not be running) has its run closed as cancelled and goes back to todo. A task that was ready for an agent gets a stopped (cancelled) run. Either way it waits in Needs you as Stopped, and General does not start it by itself. A plan step still waiting on another step in the room gets none, and runs once that step is retried and done. One waiting on a task outside the room is stopped like a ready one, since that task can finish without anyone retrying it. A task the task runner runs moves but is not stopped, so the runner can still rerun it. A retry or a reassignment runs them from General. Finished tasks keep the room. Each task moved writes a status_changed event with reason: 'room_archived', which is what tells an open Inbox that a queued task now reads as stopped. Clawboo runs the same move each time it starts, for rooms archived before it existed. No route removes a room row; deleting the team does (the rooms table cascades).
- Path params:
id(team id),roomId(the room). - Request body: none.
Responses
400 Bad Request: a path segment is missing:
404 Not Found: no room with that id in this team, or one already archived with no unfinished tasks left in it. For an archived room that still holds some (a DELETE that failed after archiving it), the call stops and moves them as above and answers 200:
200 OK: the room was archived:
500 Internal Server Error: a DB failure:
Example
GET /api/teams/:id/onboarding
Reads the team’s Know Your Team intro state. Both agentsIntroduced and userIntroduced must be true before the team chat’s normal message box opens. userIntroText is your self-introduction, which is added to the team context of every team chat message. With nothing stored, the defaults (false, false, '') come back.
A team that already has messages in General reads as introduced: the route answers both flags true without changing what is stored, so a team you have used is not gated again. Messages in rooms, and messages set aside by a clear, do not count.
- Path params:
id(team id). - Request body: none.
Responses
400 Bad Request: the :id segment is missing:
200 OK: the onboarding state (defaults when unset):
500 Internal Server Error: a DB failure:
Example
PATCH /api/teams/:id/onboarding
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Merge-updates the onboarding state and returns the full updated state. Only fields with the correct type are applied; a non-boolean agentsIntroduced/userIntroduced or non-string userIntroText is ignored and the current value is kept. userIntroText is truncated to 4000 characters.
- Path params:
id(team id). - Request body (all optional, merged with current state):
Responses
400 Bad Request: the :id segment is missing:
400 Bad Request: the body is missing or not an object:
200 OK: the merged, updated state:
500 Internal Server Error: a DB failure:
Example
GET /api/teams/:id/activity-summary
Builds a compact, on-demand snapshot of what a team has been doing, for injection into Boo Zero’s personal chat when the user @-mentions that team. Composed from durable server state in order (brief, board, saved memory, recent chat), so it works regardless of what the browser has loaded. The sections are sized against a 2500-character budget: the Boo-Zero brief is clipped to 900, the board summary and saved memory are kept whole, and the recent-chat section (up to 30 turns, oldest dropped first) gets whatever budget remains. The recent chat is drawn from General and every active room, since the summary is of the team’s work wherever it was discussed.
- Path params:
id(team id). - Request body: none.
Responses
400 Bad Request: the :id segment is missing:
200 OK: the summary block, or null when the team has nothing to report:
500 Internal Server Error: a DB failure:
An unknown team id is not a 404: it has no brief, board, memory, or chat, so it returns
{ "content": null }. Saved memory is best-effort (a memory-store failure is swallowed and the section omitted) rather than a 500.Example
POST /api/teams/:id/chat
A message from a caller that does not pass the person check still runs. It reads Local API call in the chat rather than You, records no one as asking, and leaves the team’s failure breaker as it is.
Sends your message to one chat, General by default or the room named by roomId, and answers 202 at once. The server runs the reply and any delegated work in the background, and closing the connection does not stop it. Each chat runs on its own, so work started in a room runs beside the other chats, and the tasks it delegates are filed with that room’s id.
Target resolution happens within that chat’s roster (General: the team’s active members plus Boo Zero; a room: its live members plus Boo Zero), by priority: an explicit targetAgentId that is in the roster, then a leading @-mention (the message must start with @<agent name>, and the name must be followed by whitespace or the end of the message; a mention anywhere else in the text is ignored), then the chat’s lead (Boo Zero, else the team’s own lead if it is in the roster, else the first member). The user message is persisted under the target’s session key for that chat (agent:<id>:team:<teamId> in General, agent:<id>:team:<teamId>:room:<roomId> in a room) before that agent’s turn runs.
A team whose team-server-orchestrated:<teamId> setting is 'false' gets a 404. Nothing in Clawboo writes that value, so in practice every team passes.
- Path params:
id(team id). - Request body:
Responses
400 Bad Request: the :id segment is missing:
400 Bad Request: message is absent, not a string, or empty after trimming:
404 Not Found: the team opted out of server orchestration:
404 Not Found: roomId names no active room of this team (an unknown or archived room, or another team’s):
202 Accepted: the message was enqueued (the run has NOT finished):
404 Not Found: no team with that id, as for a tab left open on a deleted team:
500 Internal Server Error: an unexpected throw before the enqueue:
The 202 means “accepted”, not “succeeded”. Watch the reply on
GET /api/teams/:id/chat/stream. A failed delivery is not returned here; it is saved in the transcript as a role: 'system', kind: 'meta' entry. When the cause is a dropped OpenClaw Gateway connection, the server first reconnects and retries the turn once, and saves the entry only if that also fails.A team with no active members also gets the 202, but nothing is stored and no turn runs.Example
POST /api/teams/:id/chat/stop
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Stops one chat, General by default or the room named by roomId, the way the Stop button does. Other chats keep going. A Stop:
- takes effect at once, before any running turn has finished;
- stops every turn running in that chat;
- releases each task those turns had claimed back to
todo, as a clean stop: noblockedstatus, no cancelled dependents, and no failure reported to the agent that delegated it; - drops messages waiting to be delivered, and a delivery whose run had not started never starts;
- records a
cancelledrun for every tracked turn and every delegation that was ready but not started, so the board does not start the stopped work again on its own.
team-server-orchestrated check as the send route applies.
- Path params:
id(team id). - Request body (optional):
Responses
400 Bad Request: the :id segment is missing:
404 Not Found: the team opted out of server orchestration:
200 OK: the stop was applied, or there was nothing to stop:
500 Internal Server Error: an unexpected throw:
Stopping a chat with nothing running (no work has run in it since the server started, or it has been idle for 30 minutes) changes nothing and still returns
{ "ok": true }. That includes a roomId that names no room at all: unlike the ingest, Stop never answers room not found.Example
POST /api/teams/:id/chat/clear
Clears one chat: General by default, or the room named by roomId. Nothing is deleted. Each of the chat’s chat_messages rows is set aside by appending #cleared:<ts> to its session_key and entry_id, so no reader matches it again. The route also drops the resume pointers Clawboo keeps for the chat (the native-team-session:<agentId>:<teamId> keys, with :room:<roomId> in a room), so native and Codex agents start the conversation fresh on their next turn. It does not reset an OpenClaw teammate’s session: that conversation lives in the Gateway, not in Clawboo. The clear time is stored in settings (team-chat-cleared:<teamId> for General, team-chat-cleared:<teamId>:room:<roomId> for a room); that is what chatClearedAt reports on GET /api/teams and GET /api/teams/:id/rooms. Other chats are not touched. This route has no server-orchestration gate.
The rows set aside are the ones under the chat’s session keys at the moment of the clear: each team member’s key in General, each live member’s room key in a room, plus Boo Zero’s key in either.
The UI’s Clear chat does two things this route does not. First, after the call it sends
/reset to each of the chat’s OpenClaw teammates over the Gateway, exactly as typing /reset in the chat does, so in the product every agent starts the conversation fresh. It sends the Gateway’s chat.send with message: '/reset' on each teammate’s chat session key (agent:<id>:team:<teamId>, with :room:<roomId> in a room), only while a Gateway connection is up, skipping any teammate it cannot reach. A direct REST caller gets only the pointer drop. Second, only the chat’s timeline stops showing the task cards made before the clear (a task whose createdAt is earlier than chatClearedAt); the board and the chat’s Tasks card keep them.- Path params:
id(team id). - Request body (optional):
Responses
400 Bad Request: the :id segment is missing:
404 Not Found: no team with that id:
404 Not Found: roomId names no active room of this team:
200 OK: the chat was cleared:
500 Internal Server Error: a DB failure:
Example
GET /api/teams/:id/chat/stream
Server-Sent Events live-tail of one chat’s transcript: General by default, or the room named by roomId. It runs in two tiers. Tier 1 polls the durable chat_messages rows for that chat’s session keys every 750 ms on the monotonic id cursor (up to 500 rows per batch); each row’s stored data is already a serialized TranscriptEntry and goes straight to the wire. Tier 2 forwards ephemeral in-memory signals (assistant token deltas, board-projection changes, agent status) as named frames with no id: line, so they never advance the resume cursor.
The stream only reads: it never starts work, and the team’s work runs to the end with no client connected. It has no team-server-orchestrated check, since reading is safe for any team. The session-key set is resolved once at connect: in General, agent:<id>:team:<teamId> for each team member plus Boo Zero’s team-scoped key; in a room, agent:<id>:team:<teamId>:room:<roomId> for each live member plus Boo Zero’s. A member added mid-stream is picked up on the next reconnect.
- Path params:
id(team id). - Query params:
- Request body: none.
This is an SSE route, not request/response. Once the stream opens there is no JSON response body; the catalog below describes the wire frames. The one exception comes before it opens: a
roomId that names no active room of this team (an unknown or archived room, or another team’s) gets 404 with { "error": "room not found" }. An unknown team id with no roomId is not a 404: no session keys match, so the stream opens and stays open emitting only keepalives. Resume replays committed rows only: deltas, board changes, and status frames carry no id and are never replayed.Connection
On open (after theroomId check), the route answers HTTP/1.1 200 with:
: connected comment frame, a cursor event with the row id it starts from, flushes any rows already past the cursor, and replays the team’s last-known agent status per agent.
Event catalog
Only the unnamed frames and the
cursor event carry an id:, so only they move the resume cursor. The cursor event gives an EventSource a resume point before any row arrives: a connection that drops first still reconnects from where it started instead of the newest row at that moment. It is a named event with data because Safari keeps no id: that arrives without data; a client needs no listener for it. A client reconciles any board change it missed across a reconnect with a GET /api/board reload.
Deltas belong to this chat alone: a stream never forwards another chat’s deltas, so General’s stream skips every room’s, and a room’s stream skips General’s and the other rooms’. Board and status frames are team-wide, so every stream of the team receives them, each tagged with the chat it came from so a client can keep each chat’s task cards and busy state to its own. A board frame’s roomId is the task’s room (null = General; left out if the task could not be read), and it carries attention (why the task now needs a person, or null) only when the change moved the task’s status. A run-boundary status frame’s roomId is the room the run belongs to (null = General); the snapshot replayed on connect carries none.
Example frames:
Example
GET /api/teams/:id/task-prefix
The letters on the team’s readable task ids (MAR in MAR-12).
Responses
200 OK:
404 Not Found: { "error": "team not found" }.
PUT /api/teams/:id/task-prefix
Sets the letters, until the team’s first task exists. After that they never change, and neither does a team rename change them. 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. A change goes on the audit feed as a board event.
- Request body:
{ prefix: string }. Two to six letters and numbers, starting with a letter, in either case; stored in upper case.
Responses
200 OK: { "prefix": "MAR" }.
400 Bad Request: { "error": "invalid" }.
403 Forbidden: { "error": "person_only" }.
404 Not Found: { "error": "not_found" }.
409 Conflict: { "error": "locked" } (the team has a task) or { "error": "taken" } (another team holds it, or a task of a deleted team still carries it).
GET /api/teams/:id/labels
The team’s labels, by name: { labels: Array<{ id: string; name: string }> }.
POST /api/teams/:id/labels
Adds a label. Dashboard only, as above, and audited as a board event.
- Request body:
{ name: string }. One to 40 characters once trimmed. Names compare without case.
Responses
201 Created: { label: { id: string, name: string } }.
400 Bad Request: { "error": "invalid" }.
403 Forbidden: { "error": "person_only" }.
404 Not Found: { "error": "not_found" }, no such team.
409 Conflict: { "error": "taken" } or, past 100 labels on the team, { "error": "too_many" }.
PATCH /api/teams/:id/labels/:labelId
Renames a label, by the same rules. 200 OK: { label: { id: string, name: string } }. Errors as for POST; 404 also for a label of another team.
DELETE /api/teams/:id/labels/:labelId
Removes the label from the team and from every task. Takes the person check, and audited. 200 OK: { "ok": true }. 403: person_only. 404: not_found.
GET /api/team-rules/:teamId
Reads the team’s rules. You set them in the team’s settings (the gear icon in the team header) or with /rule <text> in the team chat’s message box; both write here. The text is added to every team agent’s message context, so your corrections last across sessions. With nothing stored, { "content": "" } comes back.
This route uses the param name
:teamId (not :id like the routes above). The value is still the team id.- Path params:
teamId(team id). - Request body: none.
Responses
400 Bad Request: the :teamId segment is missing:
200 OK: the rules text (empty when unset):
500 Internal Server Error: a DB failure:
Example
PUT /api/team-rules/:teamId
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Replaces the team-rules text. content is required and must be a string; it is rejected (not truncated) when it exceeds 4000 characters. Returns the stored value.
- Path params:
teamId(team id). - Request body:
Responses
400 Bad Request: the :teamId segment is missing:
400 Bad Request: the body is missing or not an object:
400 Bad Request: content is absent or not a string:
400 Bad Request: content exceeds the 4000-character cap:
200 OK: the stored rules:
500 Internal Server Error: a DB failure:
Example
GET /api/team-verify-command/:teamId
Reads the team’s verify command: the check the verification gate runs for the team’s tasks in place of the command in a worktree’s init.sh.
- Path params:
teamId(team id).
Responses
200 OK: the command, or "" when none is set:
400 Bad Request: the :teamId segment is missing:
Example
GET /api/team-plan-approval/:teamId
Whether the team asks before a plan starts: { on: boolean }. Off until a person turns it on. See Plans.
PUT /api/team-plan-approval/:teamId
Turns it on or off, and records the change in the governance audit. It changes what happens to the next plan. A plan already waiting keeps waiting for an answer, unless its agent starts a plan without asking, which closes it.
A person’s route. It takes the person check: a caller nothing vouches for gets 403 { ok: false, error: 'person_only' }. The audit row says who made the change.
- Path params:
teamId(team id). - Request body:
{ on: boolean }.
200 OK: { on: boolean }. 400 Bad Request: on is absent or not a boolean. 404 Not Found: no team has this id.
PUT /api/team-verify-command/:teamId
Sets the team’s verify command. The value is trimmed; an empty string clears it. Checks that use it record commandSource: 'configured', and each new worktree for the team’s tasks starts with it as VERIFY_CMD in init.sh. Like every route here, it answers any local caller, an agent’s shell included (see Verification limits).
- Path params:
teamId(team id). - Request body:
Responses
200 OK: the stored command:
400 Bad Request: command is absent or not a string (command (string) required), longer than 2000 characters (command exceeds 2000 characters), or more than one line (command must be a single line).
403 Forbidden: { "ok": false, "error": "person_only" }: the request did not pass the person check. A team’s check must not be its own builder’s to choose, so only a person sets it. This is a speed bump on your own computer: an agent running as your user can send the same headers.
404 Not Found: no team has this id:
verification row to the audit log with the command, the one before it and the actor.
Example
GET /api/team-agent-wakes/:teamId
Whether the team’s agents may wake each other without a person being asked once per job. Off by default. See What wakes an agent.
200 OK: { "always": boolean }.
PUT /api/team-agent-wakes/:teamId
Set that. A person’s route: it answers 403 { "ok": false, "error": "person_only" } to a request that does not pass the person check. Each change goes in the audit log, with who made it. The limits on wakes hold either way, and a job a person said no to stays no.
- Request body:
{ "always": boolean }
200 OK: { "always": boolean }. 400 Bad Request: always is not a boolean. 404 Not Found: no such team.
GET /api/team-chat
Reads the team’s peer-chat room from a cursor: the team_chat table, where each agent posts as a named peer through the TeamChat MCP server at /api/mcp/teamchat. The dashboard does not read this route. Pass teamId (the room resolves to team:<teamId>) or a roomId directly; one of the two is required. sinceSeq is the cursor (posts with seq > sinceSeq).
- Path params: none.
- Query params:
- Request body: none.
Responses
400 Bad Request: neither teamId nor roomId was supplied:
200 OK: the room posts in ascending seq order plus the next cursor:
500 Internal Server Error: a DB failure:
Example
POST /api/team-chat/exchange
Starts one bounded peer-chat exchange for a team in the peer-chat room. The first speaker (the team’s lead, or the agents in firstSpeakers) takes a turn, then each active member a turn delegates or reports to, until nobody is owed a turn or the turn limit is reached. Each speaker choice (speaker_selected) and the stop reason (turn_bound_hit) are recorded in the event log. Nothing starts an exchange by itself; only this route does, and the dashboard does not call it. The agents’ MCP clients attach to this server’s own /api/mcp/* routes on its loopback port, never to the request’s Host. The route answers when the exchange ends, so keep the request open: if the client disconnects first, the turn in progress is cancelled and posts nothing, and no further turn starts. A second exchange for the same room is refused while one runs. A paused hard-cap budget on the team or a first speaker refuses the exchange with 422; one that pauses later, or covers a later speaker, refuses that turn, adds a notice to the team chat and ends the exchange with endedReason: 'budget_paused'.
- Path/query params: none.
- Request body:
Responses
400 Bad Request: missing teamId:
409 Conflict: an exchange is already running for this room (the per-room lock refuses an overlapping kickoff):
200 OK: the exchange ran to a bound and returned its result:
404 Not Found: the team does not exist (the exchange returned error: 'team not found'):
422 Unprocessable Entity: the exchange was refused for any other reason (e.g. team has no agents, unknown first speaker: <id>, budget_paused:<scope>):
500 Internal Server Error: an unexpected throw:
Example
Error envelope
Errors use the standard{ "error": string } body. On /api/team-chat/exchange, the 409 for a running exchange and the 404 and 422 refusals use { "ok": false, "error": string } (success is { ok: true, roomId, result }). The stream route answers a roomId that names no active room with a 404 and the standard body before any stream opens; after that it has no error body: it opens a 200 event stream and keeps the connection alive through brief read errors. A rate-limited request answers 429 { "error": "Too many requests. Wait a moment and retry." } with a Retry-After header.
Source of truth: apps/web/server/api/teams.ts, rooms.ts, teamChatStream.ts, teamChat.ts, teamRules.ts and teamOnboarding.ts.
Related
- Teams: create and manage teams, leaders and team rules in the dashboard.
- Team chat: General, rooms, Clear chat and the Know Your Team intro.
- Peer chat: how agents post to each other in the peer-chat room.
- Agents API: the agents these membership routes refer to, and deleting them.
- Tools and MCP API: the TeamChat MCP server that writes the peer-chat room.
- Database schema: the
teams,agents,rooms,room_members,chat_messages,settingsandteam_chattables.