Reference
Gateway API
The local gateway's HTTP endpoints, WebSocket RPC and push events, and the method list. The Quetzal app, the web console and the Feishu channel use exactly this.
#Overview
The gateway's plain HTTP listens only on 127.0.0.1:<gateway.port> (default 7788, plus [::1]). When it is open to the LAN (gateway.lan is true, or gateway.host is not a loopback address such as 0.0.0.0), it also serves HTTPS / WSS on <gateway.host>:<gateway.lanPort> (default 7789) with exactly the same interface. The certificate is self-signed and generated by the runtime (ECDSA P-256, 10 years, secrets/gateway-tls.key / gateway-tls.crt); its fingerprint is the lowercase hex SHA-256 of the certificate DER, which native consoles pin. There is no plain HTTP on the LAN. Every control entry (app, web console, Feishu, host tools) goes through one operations layer, so they behave identically and are all audited. When web/index.html sits next to main.cjs (the web console placed there by the npm package or the Windows installer), the gateway also serves those static files.
#HTTP
| Method | Path | Notes |
|---|---|---|
| GET | /health | {ok, version, safeMode, mode}, no token required |
| GET | /auth/local | {ok, token}: only on the local plain listener, only for a browser on the same machine (connection from the loopback address, local Host header, local Origin if any); the web console logs in as soon as it opens. Anything else gets 403. A local process can read the token file anyway, so this does not widen the trust boundary. A connection forwarded through an ssh tunnel counts as local |
| GET | /, /<static file> | The web console (when web/ exists): unknown paths without an extension fall back to index.html; ETag supported |
| GET | /pair/info | {ok, fingerprint, short, body, version, tls: true}, no token required: the certificate fingerprint (full and the 1a2b 3c4d 5e6f 7a8b short form), body name, version |
| POST | /pair/start | Generates an 8-character pairing code (letters and digits, valid 5 minutes; repeated requests keep the same code while it is valid, and repeated wrong guesses lock pairing for a while), delivered with the certificate's short fingerprint via adapter notification and Feishu |
| POST | /pair/finish | {proof} (or {code} on the local plain listener) → {ok, token, fingerprint}; proof = hex(PBKDF2-HMAC-SHA256(code (uppercased, spaces and dashes removed), "quetzal-pair-v2|" + the certificate fingerprint the client saw in the handshake, 100000 iterations, 32 bytes)). Over HTTPS only proof is accepted (code gets 400), so a man in the middle with another certificate cannot pair; the client then checks the returned fingerprint. 400 missing proof, 403 wrong, 410 expired or more than 5 attempts, 429 locked |
| POST | /upload?name=&token= | Upload one attachment (≤ 50 MiB) → {ok, file: {id, name, path, rel, mime, size, kind}} |
| GET | /uploads/<rel>?token= | Download an attachment (uploads directory only; documents are served as downloads with their file name) |
#WebSocket /rpc?token=<token>
{ "id": 1, "method": "status", "params": {} }
{ "id": 1, "result": { } }
{ "id": 1, "error": { "code": "", "message": "" } }
{ "event": "state", "data": { } }#Push events
| Event | Data |
|---|---|
hello | {version, safeMode} |
state | Full state, same as status (debounced 500 ms) |
timeline | New timeline entry {id, ts, kind, title, detail} |
approval | Approval {id, action, reason, args, status} |
say | Something it says proactively |
activity | Progress {session, conv, origin, channel, ts, kind, …}; kind below |
secret | Secret-input state (never contains values) |
canvas.changed | A canvas changed {doc, conv, kind, author?} (kind: created, edited, renamed, deleted, comment, run, copied from another body) |
feishu.qr / feishu.registered / feishu.error | Feishu one-tap setup |
activity.kind: start / queued / steer / step / delta (streamed fragment) / text / tool (one event while running, one after) / alive (15-second heartbeat) / done / error. Every turn in progress is also kept as a snapshot (sessions.live) so a client can rebuild its UI at any time.
#Methods
Observe
| Method | Params | Returns |
|---|---|---|
status | — | {agent, version, body, adapter, heart, physical, stopped, paused, activity, usage, budget, approvals, soul, models, thought} |
timeline | {limit?, before?, kind?} | Timeline (newest first); detail includes the process and each tool step |
messages | {limit?} | Recent conversation |
audit | {limit?, action?} | Audit records; action: "sentinel.review" lists only review verdicts |
Converse
| Method | Params | Notes |
|---|---|---|
chat.send | {text, conv?, turn?, attachments?, mode?} | mode: steer (default, interjection) / queue / interrupt |
sessions / sessions.create / sessions.rename / sessions.archive | … | Session management; sessions can filter by channel, in progress, pinned, project and time, and sort by last update, creation time or title (pinned sessions always come first) |
sessions.pin / sessions.move | {id, pinned?} / {id, project} | Pin and unpin; put a session in a project or take it out |
sessions.search | {query, limit?} | Search sessions by title and content, one best hit per session (snippet, highlight ranges, message id) |
sessions.messages | {id, limit?, before?, from?} | One session's conversation (with process records); with from (a message id) it starts near that message (to open a search hit); in attachments, files the agent generated and attached to a reply carry by: "agent" |
projects / projects.create / projects.update / projects.delete | … | Projects: name, description, project instructions (added to the system prompt of every session in the project), color and icon, archiving; deleting a project keeps its sessions and only removes them from it |
sessions.live | — | Snapshots of turns in progress |
poke | {note?} | Poke |
Canvas (see the guide)
| Method | Params | Notes |
|---|---|---|
canvas.list / canvas.get / canvas.versions | {conv?} / {id, version?} / {id} | A conversation's canvases, one canvas in full (with comments and recent runs), version history |
canvas.create / canvas.edit / canvas.update / canvas.delete / canvas.restore | … | Create; save as a new version (with base: if the agent just changed it, it is still saved and conflict is returned); rename or change language; delete; restore a version |
canvas.run / canvas.runImage | {id, version?, timeout?} / {run, name} | Run the code in the sandbox (gated by the Run commands permission); fetch an image the run produced |
canvas.comment / canvas.reply / canvas.resolve / canvas.apply | … | Comment on a selection (sent to the agent by default), reply, resolve, accept the agent's edit suggestion |
uploads.preview | {rel, max?} | A light preview of an attachment: the beginning of its text (for xlsx, the first rows of each sheet); used by the file card's Preview in the console |
Vault: secrets, secrets.delete, secrets.pending, secrets.end.
Speech: speech / setSpeech, speechVoices, speechTest.
Tuning and safety
| Method | Params |
|---|---|
activity | {value} (0–4) |
pause | {paused} |
personality | {changes: {"tau.curiosity": 2, …}} (bounded) |
stop / unstop | {reason?} / — |
permissions / setPermission | — / {id, level: allow|review|ask|deny} |
sentinel / setSentinel | — / {enabled?, model?, timeoutMs?, classes?, onFailure?, hostMode?}: safety review settings, the available risk classes and review models |
approvals / decide | — / {id, approve, note?} |
budget / setBudget | — / {dailyTokens?, dailyCostUsd?, minBattery?, maxTempC?} |
config / setConfig | — / {timezone?, brain?, heart?} |
restart | — |
selfUpdate | — |
supervision / setSupervision | — / {enabled} |
Memory
| Method | Notes |
|---|---|
memory / editMemory / setSoul | Resident memory and personality |
journalList / journal | Journal |
notes / note / search | Notes and retrieval |
soulConfig / setSoulConfig / soulKey / syncSoul | Soul repository address (SSH only) and access mode sshMode (deploy / custom + sshKeyPath / system), local public key, sync now |
agent / setAgent | Identity |
bodies | Registered bodies |
soulHistory / soulShow / soulRevert | Memory history, diff, revert |
Models
| Method | Notes |
|---|---|
providers / saveProviders | Read / save as a whole (versioned; mismatch returns STALE_CONFIG) |
catalog / refreshCatalog / remoteModels | Model catalog |
testModel | {ok, latencyMs, message} |
moveModel / toggleModel | Global order and enable/disable |
Provider configuration shape:
interface Provider {
id: string; catalogId: string; name: string; baseUrl: string; enabled: boolean;
protocol: "openai-completions" | "openai-responses" | "anthropic-messages" | "google-generative-ai";
keys: { id: string; label: string; lastFour: string; enabled: boolean; secret?: string }[];
models: { id: string; name: string; enabled: boolean; context: number; maxTokens: number; sortOrder: number; cost?: { input: number; output: number } }[];
}
interface ProviderConfig { providers: Provider[]; quickModelId?: string }Feishu: feishu.status, feishu.register, feishu.set.
This is an overview. Field-level detail is in the repository's docs/API.md; the code is authoritative.