--- title: 'API reference' description: 'Every box publishes a browsable reference of its own HTTP surface at /api/docs, generated from the routes that box is running right now.' position: 7 --- # 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://.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](/docs/cli/reference/commands#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. ```sh # 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](/docs/home/features/security-auth#the-chat-wires-take-any-bearer-today). | | 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](/docs/home/features/security-auth#how-studio-and-the-cli-prove-themselves-to-the-box). | | 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. > [!NOTE] Which of these are a promise > The chat wires, the workflow runtime and the health routes are stable surfaces > for your own code to call. The operate routes behind the Studio screens are > documented here because your box really serves them, but they ship in step with > Studio and the CLI and are not published as a contract yet. ## 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](/docs/home/features/api): the surface itself, layer by layer, with runnable examples. - [Security and auth](/docs/home/features/security-auth): which credential each route takes and why. - [Connect your box](/docs/home/deployments/connect-your-box): getting a deployed box reachable in the first place.