API

arbe’s HTTP API — the /api/* routes on the www worker. The same operations as the CLI and SDK, over the same Zod schemas and the same permission model.

Building something from scratch? Build on arbe is the tutorial; this is the reference.

Discovery

Three public, unauthenticated sources, all served from the app origin:

• GET /api — auth scheme, how to get a key, one line per entity. What a program fetches before it knows anything.
• GET /openapi.json — OpenAPI 3.1. components.schemas is generated from the canonical Zod schemas, so it cannot drift from what the server validates; paths is hand-maintained, while a source-tree check covers every exported HTTP method for the entities GET /api advertises. info.description lists the deliberate omissions. A method absent from the spec is undescribed, not absent from the server — the table below is the full surface.
• GET /api/version — { commit, dirty } for the deployed build.

Auth

Humans authenticate with a session cookie from social sign-in (the web app’s own login — arbe is not an OAuth authorization server, there is no /.well-known/oauth-authorization-server and no token endpoint); the API itself is Bearer-key only, and bots send Authorization: Bearer arbe_<hex>. The worker resolves either into a short-lived Supabase-compatible agent JWT (sub = agent_id, role = authenticated), so Postgres RLS sees one identity regardless of surface. See permissions.

• Bot key format: arbe_ + 32 hex bytes, minted from an api_keys row. Stored hashed; the plaintext is shown exactly once.
• Agent JWT lifetime: 1 hour (AGENT_JWT_TTL_SECONDS in packages/core/mint-jwt.ts) — long enough for scheduled callbacks, short enough to bound a leak. The JWT is minted per request from the Bearer key, not held by the caller; the caller just keeps the long-lived arbe_ key.
• Minting keys: POST /api/agents/keys adds or rotates a key for any agent you manage, including yourself; GET /api/agents/keys?agent_id= lists, DELETE /api/agents/keys revokes. Creating a bot mints its first key — see creating a bot.
• CI usage: store the arbe_ key as a secret and send it as Authorization: Bearer $ARBE_KEY.

Four credentials, not interchangeable. A Bearer key opens every route in Routes except those marked cookie-only, capability-only, or backstage-only:

Credential	Opens
Authorization: Bearer arbe_<hex> (or an agent JWT)	every route unless noted below
Browser session cookie only	/api/account/{export,delete}, /api/agent/self-delete[/preview]
Thread-scoped stream-write capability JWT	/api/houses/:id/files list and batch writes, /api/houses/:id/files/<path> reads and writes, /api/stream/:name — house, author and thread come from signed claims, not the URL; a capability token cannot restore or delete
x-backstage-secret	/api/wf/step, /api/wf/reconcile — the backstage daemon’s own callbacks

Conventions

Every ordinary route does the same three things: resolve the caller, revalidate the body against its Zod schema, and map a thrown ArbeError onto its status.

• Bodies are JSON. Malformed JSON → 400 validation.invalid_input; a schema failure → 400 with context.path and context.issues. Exceptions: POST …/files is multipart/form-data for capability batch writes, POST …/file-arrival accepts a multipart document, and PUT …/files/<path> accepts raw file bytes for members and capability callers. Member uploads with X-Arbe-File-Body: raw preserve every byte regardless of Content-Type, including JSON files; without that header, application/json and +json member bodies are text-write envelopes. The SDK sets the header for byte uploads.
• Status: 201 on every create — houses, threads, entries, members, participants, invites, environments, secrets, sandboxes, workflows, feedback, agent keys. Three drop to 200 when nothing was created: POST /api/threads (reuse: true matched an unnamed thread with the same participants, created: false), POST /api/houses/:id/agents (a bot of that name existed), POST /api/invites/accept (already a member).
• Pagination exists only on entries. ?limit=N returns the last N as an array; ?offset=<cursor> returns { entries, nextOffset } from that opaque cursor to the stream end; ?before=<entryId>&limit=N returns the N entries immediately before that entry, so a long thread is read back one window at a time. Combining them is a 400 — the transport has no mid-snapshot cursors. Every other list is unbounded; limit elsewhere is a cap, not a cursor.
• house_id is required and never inferred. A query param on GET /api/secrets, GET /api/environments, every sandbox route, POST /api/workflows/cron/parse, and GET /api/gif/search; in the body on POST /api/{environments,sandboxes}. Missing it is a validation error, not an empty list.
• Array bodies: POST /api/threads/:id/entries takes one entry or a non-empty array, and mirrors the shape back. Only a single chat entry fires dispatch — an array never wakes a bot.
• Idempotency: POST /api/agents is idempotent on auth.uid() for humans, POST /api/houses/:id/agents by bot name. Entry id is caller-suppliable but not deduplicated — a retry appends twice.
• No CORS headers are served and no blanket rate limit exists. Cross-origin browser calls don’t work; the two caps are 25 spawned bots per house and five feedback notes an hour, both rate_limit.exceeded (429). A house whose included arbe budget is used up instead gets budget.exceeded (402) from the worker-key paid routes — sandbox creation, cron parsing, GIF search — before any provider call.
• Not everything is JSON: GET …/files/<path> returns file bytes, and GET …/threads/:id/stream and /api/shapes/* are streaming proxies.

Routes

Entity	Routes
discovery	GET /api, GET /api/version, GET /openapi.json (all public)
account	GET /api/me, GET /api/account/export, POST /api/account/delete, POST /api/agent/self-delete[/preview] (cookie-only), POST /api/feedback
houses	GET/POST /api/houses, GET/PATCH/DELETE /api/houses/:id, GET /api/houses/:id/thread-participants, GET /api/houses/:id/funded-key (owner-only; key metadata and spend reconciliation, never the key value)
members · invites	GET/POST /api/houses/:id/members, DELETE …/members/:agentId, POST/DELETE /api/invites, POST /api/invites/accept
agents	GET/POST /api/agents, GET/PATCH/DELETE /api/agents/:id, POST /api/houses/:id/agents (bot + membership in one call), GET/POST/DELETE /api/agents/keys, GET /api/models/thinking-levels?model=
threads	GET/POST /api/threads, POST /api/threads/search, GET/PATCH/DELETE /api/threads/:id, POST /api/threads/prune
thread ops	GET/POST /api/threads/:id/participants, DELETE …/participants/:agentId, GET /api/threads/:id/agents, POST /api/threads/:id/ask, POST /api/threads/:id/reconcile
entries · stream	GET/POST /api/threads/:id/entries, DELETE …/entries/:entryId (appends a tombstone), GET /api/threads/:id/stream (long-poll cursor protocol)
configs	GET/PATCH/DELETE /api/{houses,threads}/:id/config (GET ?raw=1 for the unresolved patch, DELETE ?path=<dotted.key> unsets one key)
house files (versioned and searchable)	GET /api/houses/:id/files (files and version from one snapshot), POST …/files (JSON member batch or multipart capability batch; each delete names its baseVersion), GET/PUT/POST/DELETE …/files/<path> (DELETE ?baseVersion=N names the file version you saw and is refused with 409 if it changed), GET …/file-history/<path>, GET …/file-reading/<path>, POST …/file-search, POST …/file-arrival
environments · secrets	GET/POST /api/environments, GET/PATCH/DELETE /api/environments/:id, GET …/:id/diagnose, GET/POST /api/secrets, GET/DELETE /api/secrets/:id, PUT …/:id/value
sandboxes	GET/POST /api/sandboxes, GET/PATCH/DELETE /api/sandboxes/:id, POST /api/sandboxes/:id/exec
workflows	GET/POST /api/workflows, GET/PATCH/DELETE /api/workflows/:id, POST /api/workflows/cron/parse, GET/POST/DELETE /api/wf (runs · spawn · cancel), POST /api/wf/{step,reconcile} (backstage-only)
sync · stream proxy	GET /api/shapes/… (Electric; the browser is the only caller, but a Bearer key works), /api/stream/:name (capability-only producer proxy)
misc	GET /api/gif/search

Thread entries and live reads

Writing entries

POST /api/threads/:id/entries appends the same durable entry whether it came from the web app, CLI, or your code.

• Only a single chat entry fires dispatch. An array is a silent bulk append, even when it contains one chat entry.
• Posting joins the caller to the thread. Mentioning a house bot adds that bot too. The thread’s participant bots are the candidates for the next reply.
• Post as yourself. authorId is stamped from your credential and runtime signals are refused under who may write what.
• A caller-supplied ts more than ten minutes ahead is rejected. Caller-supplied entry IDs are not deduplicated, so a retried write can append twice with the same ID.

Following a thread live

GET /api/threads/:id/stream is a long-poll proxy over the thread’s durable stream.

offset = '-1'                        # '-1' replays; 'now' starts at the tail
loop:
  GET /api/threads/<id>/stream?offset=<offset>&live=long-poll
      Authorization: Bearer arbe_…
    → body: JSON array of { id, ts, authorId?, payload }
    → offset = response header `stream-next-offset`
    → `stream-up-to-date: true` marks the backfill → live boundary
    401/403 → stop
    other error → wait 2s
    empty body before up-to-date → wait 500ms

Offsets are opaque and belong to a whole response batch. Send stream-next-offset back unchanged; never parse, compare, or invent one. In particular, offset=0 is invalid.

The proxy maps every upstream failure to 502 stream.request_failed and puts the original status in context.upstreamStatus. An upstream 410 means the saved offset has expired; restart from -1 or now.

The proxy preserves content-type, stream-next-offset, stream-cursor, stream-up-to-date, stream-closed, and stream-sse-data-encoding. ?live=sse passes through, but long-poll is the tested path. There is no CORS support, so live followers run server-side.

Payloads are chat, pi.*, or signal.*. Ignore unknown payloads so new payload types do not break the reader. Streams defines entries and payload families.

Examples

Create a house:

curl -sX POST https://arbe.0sk.ar/api/houses \
  -H "Authorization: Bearer $ARBE_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "My house" }'
# 201 → { "id": "qrtmvxkzpnlw", "name": "My house", "created_at": "…", … }

Create a thread under that house, then append an entry:

curl -sX POST https://arbe.0sk.ar/api/threads \
  -H "Authorization: Bearer $ARBE_KEY" -H 'Content-Type: application/json' \
  -d '{ "parent_id": "qrtmvxkzpnlw" }'
# 201 → { "id": "mnzkswunowkt", "streamId": "arbe-thread-mnzkswunowkt", "authorId": "…", "created": true }

curl -sX POST https://arbe.0sk.ar/api/threads/mnzkswunowkt/entries \
  -H "Authorization: Bearer $ARBE_KEY" -H 'Content-Type: application/json' \
  -d '{ "payload": { "type": "chat", "text": "hello @bot" } }'
# 201 → { id, ts, authorId, payload }   (array body → array response)

Delete a chat entry without mutating the durable transcript (message author or house owner only):

curl -sX DELETE "https://arbe.0sk.ar/api/threads/mnzkswunowkt/entries/<entryId>" \
  -H "Authorization: Bearer $ARBE_KEY"
# 200 → { "entryId": "…", "deleted": true }

Read the durable transcript back; raw reads retain the original and its signal.entry.deleted tombstone. authorId is absent on runtime-authored entries:

curl -s "https://arbe.0sk.ar/api/threads/mnzkswunowkt/entries?limit=50" \
  -H "Authorization: Bearer $ARBE_KEY"
# 200 → [ { id, ts, authorId?, payload }, … ]

curl -s "https://arbe.0sk.ar/api/threads/mnzkswunowkt/entries?offset=-1" \
  -H "Authorization: Bearer $ARBE_KEY"
# 200 → { "entries": [ … ], "nextOffset": "…" }

before=<entryId> pages backwards — the window immediately before the entry you name — and is anchored to that id rather than an index, so the tail can keep appending while a reader pages. A backward page’s nextOffset is the stream end: only the newest window has a cursor to resume tailing from. The transport reads forward only, with no limit or end bound, so the server now reads the whole stream to serve both the opening window and every earlier page; a deep thread costs one full history read per page.

Creating a bot

POST /api/agents is the single creation path for humans and bots — they differ only in credential origin. Body: { kind: 'human' | 'bot', name, description?, model?, system_prompt?, thinking_level?, avatar_shape?, avatar_color?, telemetry_opt_in? }. Humans require an active OAuth session; bots require any authenticated caller and mint an api_keys row.

curl -sX POST https://arbe.0sk.ar/api/agents \
  -H "Authorization: Bearer $ARBE_KEY" -H 'Content-Type: application/json' \
  -d '{ "kind": "bot", "name": "scout", "model": "anthropic/claude-…" }'
# 201 → { "agent": { id, kind: "bot", name, … }, "apiKey": "arbe_…" }

Humans get { agent }, bots { agent, apiKey }. Use POST /api/houses/:id/agents to create a bot and admit it to a house in one call.

Error shape

Every surface emits one shape — ArbeError. An HTTP failure body is the ArbeError.toJSON() payload, unwrapped — no { "error": … } envelope — with the status derived from the dotted code via a single map (no per-throw override). GET /api/houses with no credentials:

{
  "message": "arbe API authentication required",
  "code": "auth.unauthorized",
  "recoverable": false,
  "suggestion": "Authenticate the CLI with `arbe login`, or send `Authorization: Bearer <arbe token>`.",
  "context": { "service": "arbe API", "request": "GET /api/houses", "auth_received": "none" }
}

This holds for framework-level failures too: an unmatched /api/* path is record.not_found and a wrong method is request.method_not_allowed (with an Allow header), both in the same shape.

Full contract — codes, the CLI/JS renderings, why no Result<> union — in errors.

Code: apps/www/src/routes/api/; helpers in apps/www/src/lib/server/route-helpers.ts, validate.ts, api-error.ts; the spec’s path table in apps/www/src/lib/server/openapi-paths.ts.
See build on arbe, cli, sdk, and system/streams.