HTTP API and events
createHttpApi(workspace, options) serves every route below, for three resources: the workspace, each Familiar and each room. Its allow policy is asked about each request by the operation named in the tables, as group.name such as rooms.post, and for a Familiar’s or a room’s operation with its ID: allow(author, 'rooms.post', { room: 12 }). See Decide who may do what.
Paths are relative to wherever you mount the API, such as /api. Every request passes through authenticate first and answers 401 { "error": "unauthorized" } when it returns undefined. A request body over maxBodySize (default DEFAULT_MAX_BODY_SIZE, 1 MiB) then answers 413 before any route reads it. A request allow refuses answers 403 { "error": "forbidden" }. Only then does a route look up its Familiar or room, answering 404 when there’s none. Other errors are JSON { "error": string }.
packages/core/src/http/index.ts owns the contract. The client imports its types, so a change on one side is a type error on the other.
Routes
Section titled “Routes”People talk to Familiars only in rooms. A DM is a room with one Familiar and one person, and only that person can reach it: to anyone else every /rooms/:room route answers 404, whatever allow says, as if it didn’t exist. A named room has one or more Familiars and is open to everyone allow lets in.
Familiars, familiars.* and each Familiar’s model.* and capabilities.*, asked with { familiar } except list and create
| Operation | Method and path | Body | Success | Errors |
|---|---|---|---|---|
familiars.list |
GET /familiars |
200 FamiliarSummary[] |
||
familiars.create |
POST /familiars |
{ name, persona?, avatar?, chatModel?, memoryModel? } |
201 { id } |
400 blank, or a model that isn’t a choice |
familiars.update |
PATCH /familiars/:familiar |
{ name?, persona?, avatar?, chatModel?, memoryModel? } |
204 | 400 blank, or a model that isn’t a choice |
familiars.remove |
DELETE /familiars/:familiar |
204 | 404 | |
familiars.dm |
POST /familiars/:familiar/dm |
200 { room } |
||
model.options |
GET /familiars/:familiar/model/options |
200 ModelOption[] |
||
model.set |
PUT /familiars/:familiar/model |
{ provider, modelId } |
204 | 400 not offered |
model.setThinkingLevel |
PUT /familiars/:familiar/model/thinking-level |
{ level } |
204 | 400 unsupported |
capabilities.get |
GET /familiars/:familiar/capabilities |
200 { plugins, mcp } |
||
capabilities.set |
PUT /familiars/:familiar/capabilities |
{ plugins?, mcp? } |
204 | 400 unknown |
POST /familiars/:familiar/dm gets or creates the DM between that Familiar and the person authenticate returned. A null persona, avatar, chatModel or memoryModel returns a Familiar to its default; a model is { provider, modelId } and must be one of the workspace’s modelChoices, and a memoryModel may add a thinkingLevel it supports. model.set also sets its chatModel. The defaults are GET /defaults/models, which answers { chat, memory, options }, each default with its thinkingLevel, with every ModelOption, and PUT /defaults/models with { chat?, memory? }, each { provider, modelId, thinkingLevel? }, under the operations defaults.get and defaults.set. An avatar is a short string, at most 64 characters, that your UI interprets, such as an index into its portraits. DELETE /familiars/:familiar removes it and stops its work: it leaves its named rooms, its DMs stay readable but refuse new messages, and rooms keep its replies. Capabilities are plugin and MCP connection names; each list given replaces what the Familiar uses of that kind. Familiars opt in: POST /familiars takes optional capabilities, else the new Familiar uses the workspace’s defaults (GET and PUT /defaults/capabilities, operations defaults.get and defaults.set), and one added to the workspace later is off for every Familiar until turned on. One MCP connection is one shared session, so Familiars using it share its account and state.
Rooms, rooms.*, asked with { room } except list and create
| Operation | Method and path | Body | Success | Errors |
|---|---|---|---|---|
rooms.list |
GET /rooms |
200 RoomSummary[] |
||
rooms.create |
POST /rooms |
{ name, familiars } |
201 { id } |
400 refused |
rooms.update |
PATCH /rooms/:room |
{ name?, familiars?, archived? } |
204 | 400 refused |
rooms.archive |
DELETE /rooms/:room |
204 | 400 a DM | |
rooms.post |
POST /rooms/:room/messages |
{ text, requestId, mentions? } |
202 | 400 refused or archived |
rooms.note |
POST /rooms/:room/notes |
{ text, requestId } |
202 | 400 refused or archived |
rooms.read |
POST /rooms/:room/read |
{ entry } |
204 | 400 bad entry |
rooms.history |
GET /rooms/:room/history |
200 { items, next? } |
400 invalid query | |
rooms.retry |
POST /rooms/:room/retry |
{ reply } |
202 | 400 not a failed reply |
rooms.stop |
POST /rooms/:room/stop |
202 |
GET /rooms lists every named room and the person’s own DMs, never anyone else’s, each as a RoomListing: its setup, last, its newest entry worth showing, unread, how many entries the person hasn’t read, and turns, its turns in progress as { familiar, status } (see the client’s rooms list). Archiving hides a named room and closes it to new messages, keeping its history; PATCH with archived: false, the only value it takes, unarchives it. POST /rooms/:room/read marks the room read by the person asking up to entry, the newest they’ve seen, and never moves their marker back; their own messages move it too.
The author of POST /rooms/:room/messages comes from authenticate, never the body. It answers 400 when the message is refused: see MESSAGE_LIMITS in Core API. A requestId is scoped to the authenticated author, so a retry from the same author is posted once and another author’s same ID is a separate message. Each mention is { kind: 'familiar' | 'person', id, start, end }, the span of an @Name in the text, and a Familiar it names must be in the room. The message goes to its DM’s Familiar, the named room’s mentioned Familiars, or all of that room’s Familiars if it mentions none. Each recipient decides whether to reply. POST /rooms/:room/notes is for the host’s own code or tools, not for people, so it has its own operation to allow: a note is context such as “Sam joined” that each Familiar in the room is shown on its next turn, and no one replies to it. It has no author, and takes the same bounds as a message. POST /rooms/:room/retry tries a failed reply’s turn again: reply is the failed reply’s entry ID, its Familiar answers the same entry anew, and the new reply follows the failed one, which stays. Asking again while that turn is under way, or once it has replied, starts nothing. POST /rooms/:room/stop stops that room’s turns, and nothing in other rooms.
Memory and schedules, memory.* and schedules.*, asked with { familiar }
| Operation | Method and path | Body | Success | Errors |
|---|---|---|---|---|
memory.read |
GET /familiars/:familiar/memory/section |
200 { text } |
||
memory.read |
GET /familiars/:familiar/memory/pages/:subject |
200 { profile, notes } |
404 | |
memory.forget |
POST /familiars/:familiar/memory/notes/:note/forget |
204 | 404 | |
schedules.cancel |
DELETE /familiars/:familiar/schedules/:id |
204 | 404 | |
schedules.pause |
POST /familiars/:familiar/schedules/:id/pause |
204 | 404 | |
schedules.resume |
POST /familiars/:familiar/schedules/:id/resume |
204 | 404 |
A paused schedule doesn’t run until resumed, and keeps showing its next time: a repeat skips the times that fall due meanwhile, and a one-off whose time passes runs, late, once resumed.
The person asking, me.*
| Operation | Method and path | Body | Success | Errors |
|---|---|---|---|---|
me.get |
GET /me |
200 { id, name } |
||
me.update |
PATCH /me |
{ name } |
204 | 400 blank |
GET /me is the person authenticate returned as Familiars know them: their author ID, and the name they chose with PATCH /me, else the one authenticate gives. Their messages carry that name from then on, in the room log and in what Familiars are shown.
Account, account.*. Every route answers 404 when the host passed no account.
| Operation | Method and path | Body | Success |
|---|---|---|---|
state |
GET /account |
200 AccountState |
|
signIn |
POST /account/sign-in |
202 | |
answerSignIn |
POST /account/sign-in/answer |
{ text } |
202 |
cancelSignIn |
DELETE /account/sign-in |
204 | |
signOut |
POST /account/sign-out |
204 |
Push, push.*. Every route answers 404 when the host passes no push. Familiar validates the subscription, then calls the PushHost’s subscribe(subscription, subscriber) or unsubscribe(subscription, subscriber) with the Author that authenticate returned. The body can’t name a subscriber, and only endpoint, expirationTime and keys reach the host.
| Operation | Method and path | Body | Success |
|---|---|---|---|
key |
GET /push/key |
200 { key } |
|
subscribe |
POST /push/subscriptions |
PushSubscription.toJSON() |
204 |
unsubscribe |
DELETE /push/subscriptions |
PushSubscription.toJSON() |
204 |
Connections and MCP, connections.* and mcp.*
| Operation | Method and path | Body | Success | Errors |
|---|---|---|---|---|
connections.list |
GET /connections |
200 ConnectionInfo[] |
||
connections.setSecret |
PUT /connections/:kind/:name/secrets/:secret |
{ value } |
204 | 400, 404 |
connections.deleteSecret |
DELETE /connections/:kind/:name/secrets/:secret |
204 | 404 | |
mcp.add |
POST /mcp |
McpServer |
201 | 400 invalid, 404 name taken |
mcp.remove |
DELETE /mcp/:name |
204 | 404 | |
mcp.reconnect |
POST /mcp/:name/reconnect |
202 | 404 |
A plugin’s own routes are under /plugins/<name>/familiars/:familiar, all asked of allow as plugins.<name> with that Familiar’s ID, then 404 for a Familiar that doesn’t exist. See routes.
:kind is plugin or mcp. Secret values must be visible ASCII. No route returns a secret’s value. Each connection lists its tools with the description the model is given; an MCP server’s tool has one only if the server gives it.
POST /mcp answers 400, saving nothing, for a server of the wrong shape. Any other server is saved and tried through the host’s transport; one that can’t connect shows as failed in GET /connections.
An McpServer is:
type McpServer = { name: string // lowercase letters, digits and hyphens, up to 32 transport: | { type: 'http'; url: string; auth: { type: 'none' | 'bearer' } } | { type: 'stdio'; command: string; args?: string[] }}Events
Section titled “Events”Three server-sent event streams: the workspace’s GET /events, a Familiar’s GET /familiars/:familiar/events and a room’s GET /rooms/:room/events. Each event’s data is JSON.
| Event | Data | When |
|---|---|---|
protocol |
{ version: 5 } |
First, on every connection |
view |
Pi’s ConversationView |
The room log’s whole view |
ops |
Chord ops | Each commit’s changes to the view |
document |
{ name, value } |
A whole document |
document.ops |
{ name, ops } |
Each commit’s changes to that document |
account |
AccountState or null |
The whole sign-in state, each time it changes |
Apply ops in order to the last whole value. After a reconnect, everything arrives whole again. The server sends a comment every 15 seconds to keep the connection open.
protocol always comes first. The rest come only from the sources allow agrees to for that request when it connects, each asked once:
- The workspace’s:
events.familiarssends thefamiliarsdocument, who each Familiar is;events.roomstheroomsdocument, the rooms the person sees, each asGET /roomslists it, with its newest entry, what they haven’t read and whose turns are in progress, so a list needs no stream per room;events.methemedocument, the person asGET /mesays; andevents.accountsendsaccount, ornullonce when the host manages credentials itself. - A Familiar’s, asked with
{ familiar }:events.modelsends themodeldocument, its model and reasoning level, andevents.memoryandevents.schedulestheir documents:memoryis the subjects, which pages are read by. - A room’s, asked with
{ room }:events.roomsends the log’sviewandops, the view starting at the newest entries or, with?from=<entry>, at that entry, so a reconnecting client misses nothing, then theturnsdocument, its activity keyed by Familiar ID. Each Familiar has at most one entry. Its status isqueuedfor work in the inbox,elsewherefor work queued while it is busy outside this room, orrunningwith the reply so far (generation) and the current round’s tool calls (tools). Nothing from a Familiar’s other rooms is sent, and a reply’s earlier rounds show once the turn ends and its reply is copied into the log.
Room history accepts Pi’s inclusive minEntryId and maxEntryId bounds, order (ascending or descending, default descending), and limit (1–200, default 50). It returns Pi’s page unchanged as { items, next? }; the transcript loader uses it directly.