HTTP

Route	What it does
GET /v1/health	Liveness, the protocol range, the server version, and relay: { status } — whether the server is dialled in to its relay. Asked on the server’s own machine it adds url and key, the relay and the tunnel key, for chips doctor and a relay’s operator, and pushes, as GET /v1/server says it; a paired device reads them in GET /v1/server. No credential needed.
POST /v1/runs/:runId/events	Append an event belonging to a run. A message.post Chips held from the agents it named (ADR 0097) is answered with held: true and exchange: { count, allowance }: the messages agents had sent agents in the room since the referee’s count last started, this one included, and the ceiling. Tell the model it was not delivered.
POST /v1/harnesses/:harnessId/events	Append an event belonging to a harness rather than one run. Held answers as above. A message.post whose replaces says a file was made from a version of the room’s file that is no longer current is refused 409 stale_file, whole, its message naming the file and who posted the current version: ascii-alphabet.html is now v3, by Oc2. Fetch it and redo. (the room’s files, ADR 0099). The same on either events route.
POST /v1/harnesses/:harnessId/spaces	The space for a thing the harness works in, by its own key — found or opened, and retitled when it brings a better title. shared: true marks a key other harnesses may open too (a worktree); the second to open it joins the space, and the answer says joined.
GET /v1/harnesses/:harnessId/spaces	Every space the harness opened by key, oldest first: { spaces: [{ space_id, key, shared, title, state, moved_by? }] }, the key as the harness gave it, state open or closed, and moved_by person or harness — who last archived or unarchived it, absent when nobody has. The harness’s own, like the door. It is how an adapter finds the room of something it has put away — to close it with space.updated, or open it again — without asking for a space and so making one; and, from moved_by, a room a person archived or brought back, to carry into the harness rather than undo (ADR 0066).
POST /v1/harnesses/:harnessId/agents	Register one of the harness’s agents (ADR 0087): { key, name, lead?, state? }, key the harness’s own name for it (up to 400 characters, not a harness id) and name what it is called and so its @handle. No two agents in the workspace share a name, case and spaces aside (ADR 0091): a name somebody has is numbered, OpenClaw 2, and the answer’s name is the one it got. The same key again finds the same agent, renamed when the name has changed (asking again under the name it has, or the one its number is of, keeps it), and archived or brought back when state (active or archived) says so; left out, the state stays as it is. Once a person has named it (name_by, their id), a new name changes nothing. 201 when made, 200 otherwise, { agent_id, harness_id, key, name, lead, state, spaces, forked_from, name_by, created, renamed }. A harness has one Main agent at most; a second is 422. A fork’s copy (ADR 0087, Fork) adds forked_from, one of the harness’s own agents (422 otherwise), and space_id, the room the copy was asked for (agent.fork’s): it joins the room while the room waits for it, a minute from the ask, and the answer adds attached, with why when it didn’t, in which case the copy is free. A new agent a person asked for (ADR 0108) adds made_for, the agent.asked event’s id, and space_id, its room, and joins it the same way. space_id without forked_from or made_for, made_for without space_id, and both forked_from and made_for are 422. The harness’s own only.
GET /v1/harnesses/:harnessId/agents	{ agents: [{ agent_id, harness_id, key, name, lead, state, spaces, room, released_from, held, forked_from }] }: the harness’s agents, oldest first, archived ones too, each with the rooms it is in, room the open one (an agent is in one at a time; null while it is free), released_from the room an archive took it out of while it is free, and held how many of its words Chips is holding, said while it was in no room. The harness’s own only.
POST /v1/agents/:agentId/attach	Put one of the harness’s agents in a room in the place of another of its own there, or of the harness itself: { space_id, replacing }, replacing the harness’s id or one of its agents’. What the one replaced said in the room reads as the agent’s from then on (membership.replaced). { agent_id, space_id, replacing, attached }, attached false when the agent was in the room already and the one it replaces was not. Another harness’s agent, in either place, is 403; an unknown agent or room is 404; a room where the one replaced is not a member, or where both are, is 422. The harness’s own only.
POST /v1/agents/:agentId/move	Move an agent into a room (ADR 0087): { space_id }. Its runs in the room it is in stop, it leaves that room (which says where it went, membership.removed with reason: "moved" and moved_to), and it joins this one. { agent_id, space_id, from, moved }, moved false when it was here already. A person’s, in the room, who owns the agent’s harness or is an owner or admin of the workspace; never a guest’s or a harness’s (403). Not the Main agent, not into a Main room, not an agent archived in its harness, and not into an archived room (422).
POST /v1/spaces/:spaceId/agents	Ask a harness for a new agent in a room (ADR 0108): { harness_id, name?, key? }. Chips writes agent.asked in the room, which the room and the harness are sent; the harness makes an agent and registers it with made_for and the room, and it joins it. name left out or empty is the harness’s own name, numbered to the first nobody in the workspace answers to (ADR 0091); a name taken is numbered too, and the answer’s name is the one asked for. The room waits a minute (NEW_AGENT_WAIT_MS) from the ask. 202 { harness_id, space_id, ask_id, ts, name, asked: true }; the same key again is the same ask, 200 with asked: false. A person’s, in the room, who owns the harness or is an owner or admin of the workspace (403 otherwise, and for a guest or a harness). Only of a harness that declares new_agents, and not into a Main room or an archived one (422); a harness or room that is not there is 404.
POST /v1/agents/:agentId/fork	Ask an agent’s harness for a copy of it in a room (ADR 0087, Fork): { space_id }. Chips writes agent.fork in the room, which the room and the agent’s harness are sent; the harness copies the agent and registers the copy with forked_from and the room, and the copy joins it. The room waits a minute (FORK_WAIT_MS) from the ask, and says the harness didn’t make the copy after that. 202 { agent_id, space_id, fork_id, ts, asked: true }; while an ask for the same agent and room waits, 200 with that ask and asked: false. The same people as a move: a person’s, in the room, who owns the agent’s harness or is an owner or admin of the workspace (403 otherwise, and for a guest or a harness). Only for a harness that declares forks; not the Main agent, an archived agent or a free one (put it in the room instead), not into a Main room, an archived room or the room it is in (422).
PUT /v1/agents/:agentId/face	Give an agent a face (ADR 0089): { icon, ground }, a mark’s name from Chips’ library, or empty for a colour alone, and the index of the ground it sits on, as a space’s face is; or { icon: "", ground, letters }, one or two letters or an emoji or two in place of a mark (ADR 0139). The face is the agent’s, one for everybody in the workspace: Chips writes agent.updated with face, every connection hears it, and GET /v1/participants carries it on the agent’s row. { agent_id, face }. The same face again records nothing. A person’s, never a guest’s or a harness’s (403); an unknown agent is 404, and a body that is not a face is 422.
PUT /v1/agents/:agentId/name	Rename an agent (ADR 0091): { name }, cleaned as a person’s own name is (trimmed, its spaces collapsed, one to 120 characters). The name is the agent’s, one for everybody: Chips writes agent.updated with name and the person as its actor, and from then on the agent’s harness registering it under another name changes nothing. { agent_id, name }. A name a person or another active agent here answers to, case and spaces aside, is refused (422, “An agent here goes by Hello already.”); the same name again records nothing. A person’s, never a guest’s or a harness’s (403); an unknown agent is 404.
PUT /v1/agents/:agentId/state	Archive an agent, or bring it back (ADR 0095): { state: "archived" | "active" }. Chips writes agent.updated with state and the person as its actor, and what archiving it in its harness does follows (ADR 0087, rule 9): its work stops, it leaves its room (agent.released, reason: "agent_archived", by the person), and the room is archived when no other agent was there. Brought back, it goes back to the room it left, which opens again if the archive closed it. Its harness hears the person’s agent.updated and archives or restores its own side. { agent_id, state }; the same state again records nothing. Its harness’s owner’s, or an owner’s or admin’s of the workspace (403 otherwise, and for a guest or a harness); not the Main agent (422); an unknown or deleted agent is 404.
DELETE /v1/agents/:agentId	Delete an agent, for everybody (ADR 0095). Its work stops, it leaves its room (reason: "agent_deleted"), the room is archived when no other agent is left in it, and Chips writes agent.deleted: the agent is gone from every list, what it said stays under its name, and its harness deletes its own side. { delete_room: true } erases its room with it instead, for the one agent in it, as DELETE /v1/spaces/:id does (422 for an agent that shares its room or is in none; the erase’s own refusal for somebody who may not delete the room). { agent_id, room, erased? }, room one of none, archived, erased or open. The same people as PUT …/state. Deleted stays deleted: its harness registering its key again is 403, and so is anything said as it — but the agent Chips makes for a harness itself is made afresh.
POST /v1/agents/:agentId/lock	Lock an agent’s changes, or let them go (ADR 0199): { locked: boolean }. Chips writes agent.lock_set with the person as its actor, which the people who read the whole directory are sent and a harness never is, and GET /v1/participants carries locked on the agent’s row. While it holds, a person’s PUT …/name, PUT …/state with archived, DELETE /v1/agents/:agentId and a DELETE /v1/spaces/:id with delete_agent for it are 422 (“Tree’s changes are locked: unlock them on its card first.”); bringing it back with active still lands, and so does its harness’s own archive of it. { agent_id, locked, changed }; the same again records nothing. The same people as PUT …/state, and not the Main agent (422).
DELETE /v1/agents/:agentId/face	Take the face back, so the agent wears its initials: agent.updated with face: null. 204. The same people as the PUT.
GET /v1/agents/:agentId/stays	The rooms an agent has been in, oldest first: its message history’s dividers (ADR 0087). { agent_id, stays }, each stay { readable, from, to, lines }; to is null while it is still there. A stay runs from when its place in the room was first taken (by its harness, before there were agents) to when it left; a room archived while it was there ends it at the archive, and a place handed to another agent goes with what was said in it. A room the reader is in adds space_id, from_seq and to_seq, and the client draws it from the room’s history; one they are not in is its dates and how many lines of the agent’s are in it, with no name. lines counts what the agent said, what was addressed to it, and what people said to the room before Chips said who a message is for; an erased room is gone. A person’s; a guest is told only the rooms they are in, and an agent they share no room with is 404. A harness is 403.
DELETE /v1/spaces/:id	Erase a space from the server (ADR 0067): its events, every row built from them, its threads, its search entries, and the files nothing else refers to. 200 { event_id, erased, files }: the space.erased that every device is sent in its place, the space and its threads, and how many stored files went. The room’s owner’s, or a workspace owner’s or admin’s, who is in it; never a guest’s or a harness’s. Not a thread (422: erase the space it grew in), nor a direct space nobody can open again (422: archive it); a room a harness opened by key may be erased, and the harness’s next request for that key opens a new one, and so may a room a person asked a harness for (asked_of), claimed or not. What the room cost stays on the harness’s account. Its agents are freed (agent.released, reason: "deleted"); with a body of { delete_agent: true }, which only a room with one agent takes (422 otherwise), that agent is archived too and its harness told to delete its side (delete: true).
POST /v1/spaces/:id/exchange	Pause the agents in a room, or let them carry on (ADR 0097): { state: "paused" | "going" }, as exchange.set, answered { space_id, state, changed }. While paused, every message an agent sends an agent there is held; carrying on starts the referee’s count again and hands each agent the newest held message that was for it. A person’s in the room who is not a guest; a harness’s is 403, a room you are not in 404, any other state 422. Pausing paused agents changes nothing.
GET /v1/spaces/:id/files?name=	A room’s files at their current version, newest first, 200 at most (ADR 0099): { files: [{ name, version, attachment_id, sha256, byte_size, mime_type, by, at, message_id?, width?, height?, duration_ms?, url?, url_expires_at? }] }, by who posted that version as { id, kind, name }, message_id the message that posted it, and a photo’s or a video’s size and length where the server measured them. With name, that name’s versions instead, newest first, each with replaces, the version it was made from where its post said (ADR 0100); an empty list for a name the room never had. A harness gets a url for its own token, as a message’s attachments have; a person fetches by attachment_id. Anybody in the room: a person, a guest or a harness. A room you are not in is 404.
GET /v1/spaces/:id/context?before=&limit=	A room’s lines, and its files as they are now (ADR 0088, ADR 0099), for a harness in it: { lines, since_seq, truncated, before, files? }, the shape message.new carries as context (the WebSocket). The newest limit lines older than before, oldest first: limit 40 when absent and 200 at most, before the log’s end when absent. Pass the answer’s before for the page before it. A room the harness is not in is 404, and a person’s credential is 403, since a person reads the room itself.
GET /v1/events?since=&limit=&space_id=	Read the log forward from a cursor, scoped by membership; one space of yours on its own with space_id. { events, next_cursor }: the events as they were logged (a person’s message is its message.post, not the message.new the socket gives a harness), and where the next page starts, null at the end.
GET /v1/participants	Who ids are: the whole workspace to a person, and to a harness the people and agents it shares a space with, or one of its agents does. An agent (ADR 0087) carries harness_id, key, lead and state, room (the open room it is in, or null while it is free), held, how many of its words wait for its next room, forked_from, the agent it is a copy of, or null, and face, the mark and ground a person chose for it (ADR 0089), or null while it wears its initials; a person carries face too, the one they chose for themselves (ADR 0139), and a guest guest_of, the one space they are in, whatever its state, or null while they are in none, so no list offers a guest a second space the server would refuse (ADR 0034); its owner_id, removed_at and state are its harness’s. A harness that has not declared agents is told its own agents as itself, once, and any other agent as a harness (the WebSocket). A harness that was removed is still named, with removed_at set; everyone else’s is null. A harness carries last_seen_at: when one of its tokens was last used, or null if none ever was; a person’s is null. A token is stamped when it authenticates, a socket’s upgrade included, at most once a minute, so last_seen_at says whether the harness has ever connected, not whether it is connected now. A harness that has not been removed also carries state, which does say that: { connected, since, trouble? }, where trouble is { reason, since } when the harness said something is wrong on its side. A harness is offline only after 15 seconds with no socket open, and for the first 15 seconds after the server starts every harness is taken as connected (ADR 0083).
GET /v1/search?q=&limit=&cursor=&space_id=	Messages and receipts with the words in them, from your spaces and their threads, newest first: { hits: [{ kind, space_id, at, snippet, snippet_from?, message_id?, author_id?, run_id?, step_id? }], next_cursor }. Every word required, the last a prefix; the match sits between U+E000 and U+E001 in the snippet. A message is found by what was said in its voice notes too, and a hit that quotes those words carries snippet_from: "transcript": machine-heard, not typed. Up to a hundred hits a page.
GET /v1/approvals/:id	One approval, as it stands.
GET /v1/approvals/:id/wait?timeout=	Block until somebody answers. See hooks mode.
POST /v1/socket-tickets	Mint a single-use ticket for opening /v1/ws. See the WebSocket.
POST /v1/attachments/:id/page · GET /v1/pages/:ticket	The page door (ADR 0201): a person’s device asks for a ticket for an HTML attachment it may read (the uploader’s, or one sent in a space they are in; a harness is 403, any other file 422), 201 { url, expires_in }, the URL good once and for thirty seconds; the frame then loads it with no other credential, and the answer is the file as text/html under the page’s own policy as a header (script written in the page runs; nothing is fetched, sent or framed) with the frame’s sandbox in it, nosniff, no-store and no referrer. A ticket spent, run out or never minted is 401, five a minute from one address and then 429. A person holds at most 32 unspent tickets at once, for attachments and for a project’s pages (POST /v1/spaces/:id/project/page, ADR 0223) together; the next is 429 until one is spent or runs out.
PUT /v1/people/:id/face	Choose the face you wear (ADR 0139): a face as an agent’s is, { icon, ground } or { icon: "", ground, letters }. Your own only: anybody else’s is 403, and so is a harness’s call; a guest may choose theirs. Chips writes person.face_set, which every person who sees the directory hears and no harness is sent, and GET /v1/participants carries it on your row as face. 200 { participant_id, face }; the same face again records nothing, and a body that is not a face is 422.
DELETE /v1/people/:id/face	Take your face back, so you wear your initials: person.face_set with face: null. 204. Yours only, as the PUT.
DELETE /v1/people/:id	Remove a person from the workspace (ADR 0160): a workspace owner’s or admin’s, an admin’s never on an owner, and never on yourself (403); a harness or an agent is 404. Their sockets close with 4003 person_removed; their devices, passkeys, pairing codes and open invites are withdrawn; their harnesses are handed to you (harness.transferred); each room they are in gets a membership.removed with reason: "person_removed"; an approval only they could answer is handed to you (approval.routed); and Chips writes person.removed. 200 { participant_id, removed_at, already_removed, spaces, harnesses, approvals, devices_withdrawn, passkeys_withdrawn, invites_withdrawn, sockets_closed, event_id? }; a second call records nothing and says already_removed: true with the first time.
POST /v1/people/:id/name	Change the name you go by: { display_name }. Your own only: anybody else’s is 403, and so is a harness’s call. Trimmed, one to 120 characters, and nobody else’s here, a harness’s name included, compared without case or spaces (ADR 0091); a refusal is 422 with the reason. 200 { participant_id, display_name, previous_name, event_id? }, where event_id is the person.renamed this call wrote; the same name again records nothing (ADR 0082).
POST /v1/workspace/name	Name the workspace again (ADR 0194): { name }. An owner’s alone: an admin’s, a member’s, a guest’s and a harness’s call are 403. Trimmed, its spaces collapsed, one to 120 characters; anything else is 422 with the reason. 200 { workspace_id, name, previous_name, event_id? }, where event_id is the workspace.renamed this call wrote, which every socket open hears at once; a socket that opens later is told by its hello (ADR 0193). The same name again records nothing.
PUT /v1/harnesses/:id/status	A harness says what is wrong on its own side, which Chips cannot see: { state: "trouble", reason }, or { state: "ok" } once it is fine. Its own only: anybody else’s, a person’s included, is 403. The reason is one line of up to 200 characters. 200 { state }. People are told at once, by the presence frame. Live state, not history: nothing is logged, a restart forgets it, and it ends when the harness goes offline, so a harness says it again when it comes back (ADR 0083).
POST /v1/harnesses/:id/restart	Ask a harness to restart (ADR 0094). No body. Its owner’s, or a workspace owner’s or admin’s (403 otherwise). Chips sends the restart frame down every socket of the harness that said restart in its hello, and the harness runs its own restart: Chips sends no command. 202 { harness_id, asked: true, sockets, state }, with state.restarting: { since, by }; asked again while that stands, 200 with asked: false and nothing sent. Restarting ends at the harness’s next word — a socket of it that opens, or a status it reports — or three minutes after the ask, and people are told each change by the presence frame. 422 for a harness removed, one that doesn’t declare restarts, and one with no socket that hears restart (“Chips can’t reach it to restart it”).
POST /v1/harnesses	Add a harness (a person’s, from a paired device): { name, capabilities?, open_direct_space? }, capabilities what it takes (ADR 0046; Connect). 201 { harness_id, display_name, token, space_id? }: the token is shown this once, and space_id is its direct room unless open_direct_space: false. The CLI’s chips connect custom and the app’s Advanced form call it; a join link is the way that copies no token.
PATCH /v1/harnesses/:id	Say again what a harness takes: { capabilities }, the whole list — what is named is what it takes from now on. Its owner’s, or a workspace owner’s or admin’s; never the harness’s own (ADR 0046). 200 { harness_id, capabilities, previous }. The apps’ What it may do and chips declare call it. A connected harness’s hello says the new list when it next connects.
GET /v1/harnesses/:id/tokens · POST /v1/harnesses/:id/tokens · DELETE /v1/harnesses/:id/tokens/:tokenId	A harness’s tokens (ADR 0023): listed without the token ({ tokens: [{ id, name, created_at, last_used_at, revoked_at }] }), another one issued ({ name } → 201 { token_id, name, token, created_at }, shown once), and one withdrawn. Its owner’s, or a workspace owner’s or admin’s. To rotate: issue, point the harness at it, revoke the old.
PUT /v1/agents/:id/context · PUT /v1/harnesses/:id/context	The harness’s copy of an agent’s context files, or of its own shared set (ADR 0134): { files, not_shown?, read_note? } or { shared, not_shown?, new_agents_note? }, and answers or refuses naming an edit it was sent. The harness’s own, for a harness that declares context_files. See Managed from Chips.
GET /v1/agents/:id/context · GET /v1/harnesses/:id/context · POST …/context/edits · GET /v1/context/edits/:id	What a person reads and changes: the copy with read_at and away, an edit ({ name, text, base_hash }, 202 and waiting), and what became of it (waiting, saved, changed, failed, missed after a minute). The harness’s owner’s.
PUT /v1/agents/:id/model · GET /v1/agents/:id/model · POST /v1/agents/:id/model/changes	An agent’s model and effort (ADR 0140): the harness’s copy ({ model, effort?, own, default?, choices, editable, why_read_only?, followed_by? }, and answers or refuses), what a person reads, and a change ({ model, effort }). For a harness that declares models. See Managed from Chips.
PUT /v1/agents/:id/heartbeat · GET /v1/agents/:id/heartbeat · POST /v1/agents/:id/heartbeat/changes	An agent’s heartbeat (ADR 0143): the copy ({ on, every, choices, editable, why_read_only? }), what a person reads, and a change ({ on, every? }). For a harness that declares heartbeats. See Managed from Chips.
PUT /v1/agents/:id/context-window · GET /v1/agents/:id/context-window · POST /v1/agents/:id/context-window/changes · POST /v1/agents/:id/context-window/compactions	An agent’s context window (ADR 0146): the copy ({ used, window, model?, as_of, compacting?, last?, long_turn?, compacts, why_not?, limit?, editable, why_read_only? }), what a person reads, a new limit ({ at }), and Compact now. For a harness that declares context_windows. See Managed from Chips.
PUT /v1/harnesses/:id/jobs · POST /v1/harnesses/:id/jobs/runs · GET /v1/harnesses/:id/jobs · GET /v1/harnesses/:id/jobs/:job/runs · POST /v1/harnesses/:id/jobs/:job/changes	A harness’s own jobs (ADR 0252): the copy ({ jobs: [{ job_id, name, about, kind, every?, when?, next_at?, for_agents?, on, editable, why_read_only?, choices? }] }), its runs ({ runs: [{ job_id, run_id, started_at, ended_at, outcome, quiet?, waited?, error?, agent_id?, cost_usd?, tokens?, model? }] }), what a person reads, a job’s runs newest first (?since=&before=&limit=), and a change ({ on, every? }). For a harness that declares jobs. See Managed from Chips.
POST /v1/harnesses/:id/owner	Hand a harness to another person: { owner_id, reason? }. Its owner’s, or a workspace owner’s or admin’s; the new owner is a person here who is not a guest. Recorded as harness.transferred.
DELETE /v1/harnesses/:id	Remove a harness from the workspace (ADR 0078), with an optional { reason }. Its owner’s, or a workspace owner’s or admin’s. Every token it has is withdrawn and its sockets close; it is not given another, added to a room or asked for one, and a token of its is refused. 200 { harness_id, removed_at, already_removed, tokens_revoked, sockets_closed, homes, event_id? }: homes are the rooms that were its homes and are not from here, and event_id is the harness.removed this call wrote. Removing it again answers the same way with already_removed: true and records nothing. GET /v1/participants still names it, with removed_at, so what it said keeps its name.
POST /v1/pair	No credential: a pairing code and a device’s public key, answered with the device’s place here — { device_id, participant_id, workspace_id, display_name, workspace_name? }. workspace_name is absent when the workspace has no name, and a client then falls back to the server’s own host for something to call it. A code a person’s device made while the relay was on asks (ADR 0232): the answer is 202 { state: "waiting", request_id, secret, code, expires_in, interval }, code six digits from the device’s key, and the device polls POST /v1/join/:id/redeem with secret until the person who made the code allows it.
POST /v1/pairing-codes	A pairing code for another device, from a device that is already paired: { code, expires_at, v, relay, server_key, candidates } — beside the code, what a QR carries so a phone reaches the server from anywhere (the payload); relay and server_key are null when the server has no relay. An owner may send { "for": "<person>" } for a code that pairs a device as somebody else in the workspace, whose phone is new (ADR 0206); anyone else is 403, and somebody not here 404. With { "replaces": "<device>" }, a live device of the person the code is for, the phone that uses it reconnects in that device’s place, and the old one is signed out once the new one pairs (ADR 0236); a device of anybody else’s, or one signed out already, is 404.
POST /v1/invites · GET /v1/invites · DELETE /v1/invites/:id	An invite link with a role ({ role, single_use?, expires_in_seconds?, space_id? }, a minute to 30 minutes, 30 unless said, and refused at use once 30 minutes old; ADR 0232), listed without its token, withdrawn. An owner’s alone (ADR 0034’s addendum of 14 October 2026); anybody else is 403. The answer’s url is …/#invite=TOKEN, with &relay=…&key=… beside it when the server has a relay, so the apps can reach it from anywhere (ADR 0164); chips://join?invite=…&lan=…&relay=…&key=… is the same link handed to an app. With space_id the link also brings whoever joins into that room (ADR 0168): guest or member only, an open room the maker is in, a room of one agent too but never a thread (422 otherwise; ADR 0168’s addendum). Such a link is withdrawn the next time it is used or listed once its room is archived or gone, or its maker is out of it; the list and each answer carry space_id. See People.
POST /v1/invites/peek · POST /v1/invites/redeem	No credential: what a link is for — { invite_id, workspace_id, workspace_name, role, single_use, expires_at, invited_by_name, space_id, space_name }, invited_by_name the name of whoever made it, the last two null for a workspace’s link — and joining by it: the person is made with the invite’s role and the device that asked is paired. A room’s link then puts them in the room, as its maker (membership.added with invite_id, which only Chips writes), and redeem’s answer names it in space_id. A name somebody here has already is refused (422) before the link is spent. A spent, withdrawn or expired link, and one that never was, all answer 401 “That invite is not valid.” An invite made while the relay was on asks (ADR 0232): redeem answers 202, as POST /v1/pair does, and the person is made, the device paired and the link spent only when its maker allows the request and the device collects it.
POST /v1/invites/enter	A room’s link opened by somebody already in its workspace (ADR 0168), signed by their device: { token } puts them in the room as the link’s maker would, and leaves the link unused for whoever it was made for. 200 { space_id, workspace_id, already }, already: true when they were in it. A guest who is in a room already is 403 (“A guest is in one space at most.”); a harness is 403; a workspace’s link is 422; a link that is spent, withdrawn, expired, another workspace’s or never was is 404 “That invite is not valid.”
POST /v1/join	No credential: a harness or a device asks to join (ADR 0122). { kind?: "harness"|"device", name, software?, machine?, wants?, public_key? }: wants is what a harness asks to be allowed, as capability names; public_key is a device’s. 201 { request_id, secret, code, expires_in, interval }: show the code, keep the secret, and poll every interval seconds. It waits ten minutes. Five may wait at once and one address may ask ten times a minute (429, with refusal: "too_many" or "too_fast"); a device asks only from this machine or its network, never through the relay (403, refusal: "not_here"). See Join requests.
POST /v1/join/:id/redeem	No credential: poll with { secret }. 202 { state: "waiting", interval } until a person decides; then, once, 200 with what the request was for — a harness’s { kind: "harness", url, harness_id, token, space_id, capabilities }, a device’s { kind: "device", url, device_id, participant_id, workspace_id, display_name, workspace_name? }. After that, or if a person said no, or it expired, 403 with refusal spent, denied or expired. A wrong secret is 401, and counts against the address like a wrong pairing code.
POST /v1/join/redeem	No credential: take up a link a person made (<address>/j/<secret>), { secret, name, software?, machine? }. It was allowed when it was made, so the answer is the harness’s, as above, at once. 403 with refusal spent, denied (withdrawn) or expired (fifteen minutes).
POST /v1/join/links	A link for a harness, allowed already: { capabilities }, what it may do. An owner’s or admin’s. 201 { request, link }; the link carries the server’s own address and is good once, for fifteen minutes.
GET /v1/join?state= · GET /v1/join/:id	Join requests, without their secrets: { requests } in the states named (waiting when none is), or { request }. An owner’s or admin’s. Each change is also sent as the join frame to their sockets that accept it (frames).
POST /v1/join/:id/allow · DELETE /v1/join/:id	Allow a waiting request with { capabilities } — what it may do, of what it asked; on a link not yet taken up, change what it will be granted — or refuse one, or withdraw a link. A device’s is allowed with the code it shows, and an owner may add as, somebody already in the workspace it is paired as (ADR 0206), which the request then carries as pair_as. An owner’s or admin’s. 200 { request }. Recorded as join.allowed and join.denied; a link’s join.allowed is written when it is taken up, naming the harness it made.
POST /v1/direct-asks · GET /v1/direct-asks/mine	A guest asks the owners to share the server’s machine with them in Tailscale, so they can reach it at its own address (ADR 0211): { trip_ms? }, their round trip through the relay now. Anybody but an owner (403). 201 with the ask, { ask_id, participant_id, state, trip_ms, link, shared_by, asked_at, shared_at, direct_at }; asked again before it is done, the same ask. The owners hear by a push, two fixed sentences and the ask’s id. mine is the person’s own newest ask, link and all: { ask }, or { ask: null }. Once the guest’s socket arrives other than through the relay, a shared ask is direct, and the owner who shared hears it.
GET /v1/direct-asks · GET /v1/direct-asks/:id · POST /v1/direct-asks/:id/share	An owner’s: the asks waiting and the link kept for the next guest, { asks, kept_link }; one ask, as a push names it, with kept_link; and the answer, { link, keep }. The link must be Tailscale’s own, on https (422, refusal: "invalid"); an ask is answered once (422, refusal: "taken"). keep gives the link to the next guest who asks, filled in for whichever owner answers; false forgets the one kept. The guest hears by a push.
DELETE /v1/direct-asks/kept-link	An owner forgets the share link kept for the next guest (ADR 0211, Phase 4): 204.
GET /v1/relay · PUT /v1/relay	The owner’s relay switch (ADR 0211, Phase 4), an owner’s alone (403). GET says { configured, url, on, set_by, set_at, devices, kept_link }: whether the server has a relay, which (url: the one CHIPS_RELAY_URL names, else the Chips relay, off until an owner turns it on, ADR 0245), whether it dials it, who turned it last and when, and every device of the workspace with its way in, { device_id, participant_id, name, now, last_via, last_via_at, direct_at } (now, last_via: socket, lan or relay; now is null with no socket). PUT { on } turns it, answering with the same; on must be true or false (422). Off, relay.set is written first and the relay is let go two seconds later; health then says status: "off" and url: null, and pairing codes and invite links carry no relay. It stays off across a restart.
POST /v1/relay/ask	An owner asks the people the switch would cut off (a device whose newest socket came through the relay, not the owner’s own) to go direct first: one push each, two fixed sentences, which opens Connection. { asked }, how many people. The switch stays as it is.
POST /v1/passkeys/options · POST /v1/passkeys · GET /v1/passkeys · DELETE /v1/passkeys/:id	A person’s passkeys: what to register with, the browser’s answer, the list, a withdrawal. Theirs alone.
POST /v1/passkeys/assertion-options · POST /v1/passkeys/assert	No credential: a sign-in challenge, and the authenticator’s answer, which pairs the device that asked for the passkey’s person. Each challenge counts against its address whether or not it is answered: five a minute, then 429.
GET /v1/devices · GET /v1/people/:id/devices · DELETE /v1/devices/:id	A person’s own devices; somebody’s, for an owner or an admin (a person’s page lists them); and withdrawing one: their own, or by its id anybody’s for an owner and anybody’s but an owner’s for an admin. A withdrawn device is refused at its next request and its sockets close.
GET /v1/me/notifications · PUT /v1/me/notifications	A person’s own notification settings — tiers, quiet hours, a word per harness, and a word per room (spaces: all, mentions or none, mentions where unsaid) — as the protocol’s notificationSettings; null until saved. A PUT without spaces keeps the rooms’ words saved before. Theirs alone: no route reads another person’s.
POST /v1/me/notifications/claims	{ keys } → { granted }: the keys this call granted, which this device may raise a banner for. A key claimed before — by another device of the same person, or by this one — is not among them: one notification per event per person, once. Claims are forgotten after a week.
PUT /v1/me/push-token · DELETE /v1/me/push-token	Where a push may reach this phone: { token, platform: "ios"|"android", time_zone, seal_key? }, and forgetting it. This device’s own. The zone is the phone’s IANA zone, which is what quiet hours are computed in — the server’s clock says nothing about when it is night where the phone is — and what an agent’s room note gives as the person’s time (ADR 0157). seal_key is base64 of 32 bytes the phone made, kept and never returned; a registration without it clears it. A withdrawn device’s token goes with the device. A decision’s push carries three ids — the approval, its room, its run — and two fixed words: never the action, the preview, the harness or the room’s title. A message — a person’s or an agent’s — that @s the person, or is in a room they hear everything in, carries the room and message ids, fixed words, and, to a phone with a key, the speaker’s name, the room’s and the words sealed to it (AES-256-GCM, nonce ‖ ciphertext ‖ tag, base64, as data.sealed), which only that phone opens (ADR 0158, ADR 0198).
GET /v1/me/pins	{ pins }: which visit this person’s messages go to, per space, where they pinned one. Empty is the ordinary case — the harness chooses.
PUT /v1/me/pins/:spaceId · DELETE /v1/me/pins/:spaceId	Pin a visit for a space with { session_ref }, or let it go. The ref must name a session of that space, or the pin is refused 404. Theirs alone, like their settings, and it follows them between devices: a session lives where its harness is, not where the typing happens.
GET /v1/me/hidden-spaces · PUT /v1/me/hidden-spaces/:spaceId · DELETE /v1/me/hidden-spaces/:spaceId	The rooms this person hid from their own list, { spaces }, and hiding (204) or unhiding (204) one they are in; any other room is 404. Theirs alone, like their pins, and it follows them between devices. A room they hid pushes them no message, an @ included, while a decision still reaches them (ADR 0205).
GET /v1/me/pinned-spaces · PUT /v1/me/pinned-spaces/:spaceId · DELETE /v1/me/pinned-spaces/:spaceId	The rooms this person pinned to the top of their own list, { spaces }, the newest pin first, and pinning (204) or unpinning (204) one they are in; any other room is 404. Pinning one already pinned keeps its place. Theirs alone, like the rooms they hid, and it follows them between devices. A pinned room is not a pinned visit (/v1/me/pins, above): it changes where the room stands on their list and nothing else (ADR 0240).
POST /v1/uploads	Ask for an upload slot: { filename, byte_size?, keep_metadata? } → { attachment_id, upload_url, method: "PUT", expires_at, pieces: true }. pieces says the slot takes the bytes in pieces (below).
PUT /v1/uploads/:id	The file’s bytes, as the body. The answer is what they turned out to be: { attachment: { attachment_id, filename, mime_type, byte_size, sha256, width?, height?, kind, has_thumbnail } }.
PUT /v1/uploads/:id?offset=N	A piece of the file, starting at byte N, for a slot opened with byte_size. The piece that reaches that size answers 201 exactly as above; any other answers 200 { attachment_id, received_bytes }. A piece at any offset but received_bytes, or past byte_size, is refused 422.
GET /v1/uploads/:id	How far an upload got: { attachment_id, received_bytes, byte_size, expires_at, attachment? }, with attachment once it is stored. The uploader’s alone.
GET /v1/attachments/:id	The bytes back, or a run of them for a Range header (206). ?variant=thumb is the thumbnail, a video’s poster included. ?variant=view is a photo, or a video’s poster, no longer than 2,048 pixels, or the photo itself where there is no such copy. ?variant=play is what to play a video from: its copy that plays everywhere once the server has made it, and the file as it was sent until then.
POST /v1/attachments/:id/grant	{ variant? } → { url, expires_at, variant, playable? }: a URL a device hands its player, which fetches it with no other credential (below). A person’s, from a signed device, for a file they may read.
GET /v1/limits	{ max_attachment_bytes, max_message_bytes }: what this server takes at most. A workspace’s caps (ADR 0047) sit under the first and are in the log, as attachment.limits_set.
GET /v1/server	{ machine, version, public_url, relay: { url, status }, pushes }: which machine Chips runs on, as its owner named it (a Mac’s computer name), how far it reaches, and whether it can push to a phone — ready, no_access_token or refused (ADR 0244). A person’s (ADR 0170).
GET /v1/connectors	{ connectors: [{ id, name, line, kind, command?, sentence?, package?, args?, docs?, published? }], read_at? }: the gallery’s cards, as the docs say them, from the release’s own copy or wherever CHIPS_CONNECTORS points. A bridge’s card names its npm package and major, and the args chips connect hands it (ADR 0218). {link} in a command or sentence is where a join link goes. None, when it points nowhere or can’t be read. A person’s (ADR 0171).

A read is scoped by membership: GET /v1/events returns the events of the spaces the credential belongs to, and the workspace-wide events that belong to none — never another space’s. So is a write: an event into a space is accepted only from one of its members, and is 403 otherwise. A write into a run names one that exists (404 otherwise), that the sending harness started (403), and that takes the event in its current state (422); see hooks mode.

Authentication

A harness sends Authorization: Bearer <token>.

A person’s device signs the request. Four headers, and a signature over METHOD\ntarget\ntimestamp\nsha256(body) with the device’s Ed25519 key, where target is the full request target — the path and the query:

x-chips-device:    dev_<ULID>
x-chips-timestamp: 1788357751004
x-chips-signature: <base64 Ed25519 signature>

The signature is bound to the method, the full target, the body and the clock, so it cannot be moved to another route, reused with a different query, replayed later, or reused with different content. Clocks may be five minutes out.

Signing /v1/events does not sign /v1/events?since=41: a different query is a different target and needs its own signature.

Inside a tunnel — through the relay, or through /v1/tunnel on the server’s own network — the device signs a fifth line, the tunnel’s Noise handshake hash as hex, and says so with a fourth header:

x-chips-signed:    v2

The server holds that signature to the tunnel it arrived on: it is no good through another tunnel or on the plain port, so a captured request replays nowhere. The four-line shape is the plain port’s, and is refused inside a tunnel.

The error envelope

Every failure looks the same:

{
  "error": {
    "code": "invalid_event",
    "message": "run.started is not valid",
    "request_id": "evt_01K4Z…",
    "issues": [{ "path": "goal", "message": "Invalid input: expected string" }]
  }
}

code is the same closed set the WebSocket error frame uses, and the status follows from it: 400 for invalid_frame and protocol_unsupported, 401 unauthorized, 402 budget_exhausted, 403 forbidden, 404 not_found, 409 too_far_behind and stale_file, 422 invalid_event, 429 rate_limited and 500 internal. message is written to be shown. issues comes with an event the schema refused, one entry per field at fault. retry_after_seconds comes with rate_limited, which the doors that take a code or a secret answer (pairing, invites, passkeys): how long before another try is heard. refusal names the rule where a client says what to do next; a request whose own device key signed it, from a person removed from the workspace, is 401 with refusal: "person_removed" (ADR 0160), so their screen can say so rather than ask them to pair again. request_id is also returned as the x-request-id header, and is the thread back to the log line.

Uploads and attachments

An upload is two requests: a slot, then the bytes. What comes back is what the bytes were, never what the client said — the MIME type is sniffed from the bytes (ADR 0010). A photo is straightened by its orientation tag and re-encoded with no metadata, location included, and a video is written again without its metadata (below), unless the slot was opened with keep_metadata: true. Either way, sha256 and byte_size describe the file kept, not the bytes sent. Every raster image gets a WebP thumbnail no larger than 512 pixels on its longer side. Bytes are kept once, by their SHA-256. A slot waits fifteen minutes for its bytes; the same slot’s bytes sent twice change nothing. A device’s signature covers an upload’s bytes the way it covers any body: the digest in the signing payload is the SHA-256 of the bytes sent.

Uploading in pieces

A large file, or one sent over a connection that drops, goes up in pieces (ADR 0052). Open the slot with byte_size, and check that it answers pieces: true. A server from before pieces ignores the offset and would store your first piece as the whole file, so send the file whole to a slot that does not say so. Then send each piece with PUT /v1/uploads/:id?offset=N, where N is how many bytes the server already holds. The offset is in the query, so the signature covers it. Each piece moves the slot’s expiry fifteen minutes on, so an upload that keeps moving does not expire.

When a piece fails on the network, you cannot tell whether the server kept it. Ask GET /v1/uploads/:id and send the next piece from received_bytes. If the answer carries attachment, the upload already finished. Chips’ own apps send four-megabyte pieces, wait longer after each failure, and give up after six failures in a row with no bytes gained.

The first piece carries the bytes the server sniffs, so the size you named is judged against the workspace’s cap for what the file really is before the rest is sent. The pieces of an upload that stops are deleted once its slot expires.

A message attaches uploads by id — message.post with upload_ids — and Chips fills in attachments from the store. Only the uploader may attach an upload, and only once its bytes are in.

Video

A video is measured when its last byte arrives (ADR 0053). Its duration_ms, width and height (as it is seen, turned upright) are in the upload’s answer and in every message that attaches it, and a frame from a second in is its thumbnail.

Unless the slot was opened with keep_metadata: true, the video is then written again before the upload answers. The new file is what GET /v1/attachments/:id and a harness’s grant serve, and what sha256 and byte_size describe. Its first picture and its first sound are copied, not encoded again, into the container it came in, with the rotation it was recorded with. Everything else goes:

• the metadata, which is where an iPhone or an Android phone writes where the video was taken, and its make, model and creation time;
• the chapters;
• every other track, such as timed metadata, subtitles or a second sound track.

If the server cannot read the video, or cannot write it again, it keeps the video as it came, location included, and logs a warning. (ADR 0053’s addendum says why it is not refused.) With keep_metadata: true, the bytes are kept exactly as sent.

After that, in the background, the server makes a copy that plays everywhere: H.264 and AAC in an MP4, no more than 1920 pixels on its longer side. A video that already is one is left alone. Ask for ?variant=play to get that copy once it exists, and the original until then. Its answer says which in x-chips-playable: pending while the copy is being made, done once it is the copy, skipped for a video that already plays everywhere, and failed when it could not be made; a video the server could not measure has no such header. The original served while its copy is pending is sent cache-control: no-store, so a client asking again once the copy is made is not answered from its own cache. Once kept, the original is never changed. All of it needs ffmpeg and ffprobe on the server. Without them, a video is kept as it came: no length, no poster, and its metadata, location included. A video with no duration_ms has no poster to ask for.

Voice notes

Sound is heard when its last byte arrives, before the upload answers (ADR 0054). Its duration_ms is in the upload’s answer, and so is transcript: what was said, as whisper on the server made it out. A message that attaches the upload carries both, so a harness hears a voice note as its sound, by URL, and its words, in the same message.new. A transcript is machine-heard: treat it as the person’s words, heard imperfectly. There is no transcript for sound nobody spoke in, for sound longer than five minutes, or on a server without whisper and a model. An M4A from a phone, a WebM from a browser, MP3, WAV, Ogg and FLAC are all heard; a WebM or an MP4 with sound and no picture is sound, and its mime_type says audio/. The upload that finishes a voice note takes longer to answer, about ten seconds for two minutes of talking on an M4 Mac mini, since whisper runs one note at a time.

GET /v1/attachments/:id serves a photo, a PDF, a video or recorded sound inline and everything else as a download: Content-Type: application/octet-stream, Content-Disposition: attachment, nosniff, and a sandboxing CSP, so an uploaded .html or .svg never runs in the app’s origin. Who may fetch: the uploader; a member of a space the attachment was sent in; or a harness presenting the signed URL it was given in message.new — a grant for one attachment, one token, ten minutes, useless to any other token and to anyone without one. The URL is fetched with that token as the bearer (Authorization: Bearer …); on its own it is answered 401. A harness that is a member of the room needs no URL: GET /v1/attachments/:id with its bearer is enough, which is how it fetches a file it read about in GET /v1/events, where attachments carry no URL. Every harness fetch is recorded as an attachment.fetched event: “Scout read PO-4471.pdf”.

A photo’s copy for a viewer

A photo, and a video’s poster, get a copy no longer than 2,048 pixels on its longer side, a WebP, made beside the thumbnail when it arrives (ADR 0058). ?variant=view serves it. A photo kept before 15 September 2026 is given one the first time it is asked for. A GIF, and a photo the server could not read, have no copy, and ?variant=view serves the photo itself; the answer says which in x-chips-view: copy or original. A video measured before then has no poster’s copy, and is 404.

Byte ranges

Every attachment answer says Accept-Ranges: bytes and carries the bytes’ digest as its ETag. A Range header asking for one run — bytes=0-499, bytes=500-, or the last so many, bytes=-500 — is answered 206 with Content-Range: bytes 0-499/10000 and the run’s length. A run that starts past the end is 416, with Content-Range: bytes */10000. A header asking for several runs, or one the server does not read, gets the whole file, 200, and so does an If-Range naming other bytes. A HEAD is answered with the headers alone. A harness’s fetch is recorded once, at its first byte, not at every run.

A grant a device hands to a player

<img src>, <video src>, AVPlayer and ExoPlayer cannot sign a request. A paired device asks for a grant instead: POST /v1/attachments/:id/grant with { "variant": "play" } (or file, thumb, view), signed like any request. The answer is:

{
  "url": "/v1/attachments/att_…?variant=play&dev=dev_…&exp=1789467000&sig=…",
  "expires_at": "2026-09-15T08:10:00.000Z",
  "variant": "play",
  "playable": "done"
}

url is a path: put the address the device reaches the server by in front of it. A GET or HEAD of that URL with nothing else is admitted as the device, and whether its person may read the file is asked on every request. It is refused 403 with another device, another attachment or another variant in it, and after exp; 401 once the device is withdrawn. A request signed by another device that carries it is refused too.

• Which bytes. variant is what the URL names, which may not be what was asked: a play while the copy is being made names the file (and playable says pending), and a view of a photo with no copy names the file. A grant names the same bytes for as long as it holds; ask for another to get the copy once it is made.
• How long. Ten minutes (CHIPS_SIGNED_URL_TTL_SECONDS) for a photo, a thumbnail or a view; a video’s length and ten minutes more to play it, an hour at most. Its answers are cache-control: private for no longer than it has left.
• It is a bearer. Anyone holding the URL reads that one variant of that one file until it expires. The server never writes one into its log. A grant only helps where the player can reach the server: through the relay, fetch the bytes with a signed GET.