The API surface

Every workspace serves one HTTP API. Locally it listens on port 9100; a hosted workspace serves the same API at its own origin. This page is the map of that API: every public door in one place, grouped by what a person does with it, and a short list of the prefixes that belong to the machinery and are not part of the public surface.

It was read from the source of version 0.224.0. Where a door has a page of its own, the last column links to it; the API reference carries request and response shapes for many of them.

How to read this page

A public door is one you, your client, or a program you write calls on purpose. It takes an ordinary credential (a bearer token, or the local socket when you are on the machine that runs the workspace), answers JSON, and refuses with a small envelope: {"object": "error", "code": "...", "message": "..."}. A few doors are open without any credential, on purpose: the liveness probe, the capability manifest, the sign-in doors, invite preview and redemption, and public links. Those are marked open below.

An internal door is one the workspace's own moving parts use to talk to each other: a run's worker asking whether it may make a call, the model relay a worker speaks through, the feeds two workspaces exchange when they sync, the pairing handshake, the identity directory. They are listed by prefix at the end and are not documented as an API. Their shape can change between releases without notice.

Paths say actors in several places. On screen, and everywhere else in these docs, those are members: people and automated agents alike. A {did} in a path is a member's id, the one spl actor list prints.

Workspace and records

Threads and runs

Your call

The lane of things waiting on a person. A decision needs an answer; a heads-up needs only a nod.

The register door

GET /v1/register answers one object. The fields a client renders from:

• configured: whether this workspace has been set up at all. An empty register with configured: false is a bare workspace, not a quiet one.
• asks: the ranked rows, duplicates merged. asks_open counts every open item before folding, asks_distinct after.
• asks_decisions and asks_notices: the split of those rows into decisions (an answer is needed) and heads-ups (a nod is enough). A badge that counts what needs a person reads asks_decisions.
• asks_receivable and asks_unreceivable: how many of the rows a run can still take the answer to, and how many nothing can receive any more.
• asks_capped and ask_scan_ceiling: whether the ask counts are exact or a floor, and the ceiling they were measured under. capped is the combined signal for asks and proposals together.
• proposal_groups: open proposals grouped by identical text, each with its summary, count, confidence, latest_clock and decision_ids. Deciding any one member of a group settles the group. proposals and proposals_open are the ungrouped list and its count.
• rules, rules_live, rules_re_asked: the answers that became standing policy, and which of them have come back as a question.
• weights, oldest_ask_unix, viewer, root_thread.

The decide door

POST /v1/decisions/{id}/decide takes {decision, reason?, provided_value?, becomes_policy?}. For an item that offers options, decision is the chosen option's id (approve or reject for the plain pair). For an item that asks you to provide something, decision is "provide" and provided_value carries the answer. For a heads-up, decision is "acknowledge". becomes_policy turns the answer into a standing rule with an expiry.

The answer is {object: "decision", id, request_id, decision, policy, opened_thread}, plus fulfills (an answer) or cancels (a rejection) naming the request id again. opened_thread is the thread this answer opened, when it opened one; it is null for an ordinary item. A fresh workspace set up with any preset other than blank seeds one question in the register, "What are you working on?", and answering it opens your first thread, titled with exactly what you typed, and returns its id here so your client can take you into it. Answering the same question twice returns the same thread. See First run.

Members

Permissions, rules and tools

Sharing and public links

Files

Identity and sign-in

Operations and health

Internal doors

These prefixes belong to the workspace's own machinery. They are not the public surface, they are not documented here, and their shape can change between releases without notice.

• /v1/work/tool-verdict and /v1/work/tool-call: the seam between a run's worker and the workspace that judges each of its tool calls.
• /v1/broker/: the model relay a worker speaks through, so the worker never holds a model credential.
• /v1/sync/ and /v1/federation/: the feeds and pairing handshake two workspaces use to exchange records and files. You drive them with spl federation pair and spl sync; see Federation.
• /v1/discovery/: finding peers on the local network.
• /directory/ and /v1/directory/publish, /v1/directory/self-delist: the identity directory service and the doors other workspaces and the provisioning service push into.
• /v1/admin/provisioning-worker-restore: the provisioning service's own door.
• /v1/patterns/: cross-workspace pattern evaluation.
• The relay, which carries messages between workspaces that cannot reach each other directly, is a separate service with its own doors; see Relay.

Stability

Doors are added, and fields are added to existing answers, in ordinary releases without notice; a client that ignores fields it does not know keeps working. A breaking change is a door renamed or removed, a field whose meaning changes, or a call that used to succeed and now refuses. Breaking changes are called out in the release notes and in the source changelog, with the migration; a removed path answers 404 from the release that removes it, the way the older /v1/agent/* paths did when they became /v1/work/*. The capability manifest at GET /v1/capabilities carries a manifest_version that changes only when the manifest's own shape breaks, so a client can detect that before it parses.

Internal doors carry no such promise.