API reference

Your box documents itself. It serves a browsable reference of its own HTTP surface at /api/docs, and the OpenAPI 3.1 document behind that page at /api/openapi.json. Both are built from the routes the box is running when you ask, so what you read is that box, not a release note about it.

Open it

The reference lives on the box, at the same address as everything else it serves:

Where the box is	Open
On your machine, stackbone dev	http://127.0.0.1:4242/api/docs
On the tunnel stackbone dev opens	https://<your-tunnel>.tun.stackbone.ai/api/docs
Deployed	https://your-box.example.com/api/docs

The tunnel address is the one stackbone dev prints when it starts, the same one Studio uses to reach your local box. A deployed box listens on 8080, or on PORT when your platform sets one, at whatever address you gave it (see Going to production).

Both routes answer without a credential, on every box. They describe the shape of the surface and never a byte of your data, so you can read the reference before you hold a token.

# The document itself, for a tool rather than a browser
curl https://your-box.example.com/api/openapi.json

Read it by surface

Operations are grouped by surface, and each group opens with a sentence saying what that surface is and who calls it. That matters more than it sounds: the box serves several audiences on one port. Some routes are for the Studio screens, some are the wire your agent process talks to its own box on, some are a redirect an outside identity provider sends a browser into, and the three chat wires are for any client you point at an agent. The tag tells you which one you are reading.

Every operation also carries a stable operation id derived from its surface and its action, such as runsGetById or secretsPost. Nothing renumbers when a route is added elsewhere, so a client you generate today keeps its method names tomorrow.

Try a call from the page

The page has a "Try it" panel per operation. It sends a real request to the box you loaded the page from, so what you get back is a real answer.

Routes	What to put in the credential field
Health, the handshake, the reference itself	Nothing. They take no credential.
Agent chat (/openai, /anthropic, /agui)	Any non-empty bearer key, in Authorization or x-api-key. See the chat wires.
Workflow and operate routes on a deployed box	The short-lived identity token the control plane mints for your session, as a bearer. See how Studio proves itself.
Anything on a local box	Nothing. stackbone dev verifies no token at all.

That last row is why the reference is most useful on the local loop: under stackbone dev every operation is one click from a real response.

An operation that wants a signature instead of a bearer says so on its own entry. Those are the routes your agent process calls on its own box, and the signing key never leaves the box, so they are not the ones to drive by hand.

The document is generated, not maintained

The box builds the document from its live route table each time you ask for it. Two consequences worth knowing:

• A box only describes what it serves. A workspace with no deep agents shows no chat wires, because it answers 404 on them. A box with no inbound trigger wired shows no trigger routes.
• Late arrivals appear. Your workflows compile after the server is already listening. Reload /api/docs once the box reports ready and they are in it.

So a reference that is missing something you expected is telling you about the box, not about the documentation. Check the box serves the thing first.

Every described response has a named shape

Where the reference shows a response body, it points at a named schema rather than an anonymous blob pasted into the operation. The same named shape is what Studio renders and what a generated client is typed against, so the body on this page is the body the box has agreed to answer.

If you meet an operation whose response has no named shape, read it as a gap in the contract rather than as licence to guess: the shape belongs in the shared contract that every reader of the box uses, not on that one route. Say so, and it is added there.

Point a tool at it

/api/openapi.json is an ordinary OpenAPI 3.1 document. Import it into an API client, hand it to a client generator, or diff two of them to see what changed between two builds of your box. Because the operation ids are derived rather than numbered, that diff shows the routes that actually changed instead of every route below the first insertion.

What's next

• API: the surface itself, layer by layer, with runnable examples.
• Security and auth: which credential each route takes and why.
• Connect your box: getting a deployed box reachable in the first place.