> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

Base URLs, authentication, conventions and error formats of the B3OS beta API, and how this reference is generated from the OpenAPI document.

Every endpoint in this reference is generated from the B3OS OpenAPI document, which is also served at `https://beta-api.b3os.org/openapi.json` (OpenAPI 3.1). The pages here render a 3.0.3 copy of it.

## Base URLs

| URL | Who calls it |
|---|---|
| `https://beta-api.b3os.org` | Your code, with an API key or a CLI token |
| `https://beta.b3os.org` | The dashboard, with its session cookie. Same paths. |
| `http://127.0.0.1:7700` | Code inside a B3OS sandbox, with no key. The sandbox's grant decides what it may call. |

Account operations (keys, usage, limits, organizations, projects, sign-in and the pack registry) exist only at `https://beta-api.b3os.org`; the in-sandbox URL answers them with [`421 edge_only`](/errors#edge_only). Artifact downloads and sandbox port previews are served only through `usercontent.b3os.org`, never through the API host, so their pages here have no working request panel.

## Authentication

Send a credential as a bearer token:

```bash
curl -s https://beta-api.b3os.org/v1/keys/current -H "Authorization: Bearer $B3OS_API_KEY"
```

API keys start with `b3os_sk_` and CLI tokens with `b3os_pat_`. Each operation needs one [scope](/concepts/auth#scopes). Three streams also accept a single-use [stream ticket](/concepts/auth#stream-tickets) for browsers.

## Conventions

- **Objects** carry `id` (a [prefixed ID](/concepts/ids)), `object`, `created_at` and `metadata`, plus `status` where it applies.
- **Lists** take `?limit=` and `?cursor=` and return `{"object": "list", "data": [...], "next_cursor": ...}`.
- **Long-running work** is a [job](/concepts/jobs): add `?wait=`, stream with `Accept: text/event-stream`, or pass a `webhook`.
- **Writes** accept `Idempotency-Key` for safe retries.
- **Every response** has `x-request-id` and [`Server-Timing`](/concepts/timing); bodies of operations that do work also carry `timing`.
- **Limits** are listed by `GET /v1/limits`; throttled calls return `429` with `Retry-After`. See [limits](/concepts/limits).

## Errors

Native endpoints return RFC 9457 problems (`application/problem+json`) with a stable `code`; the [errors page](/errors) lists every code. Three surfaces keep their upstream shapes instead:

| Surface | Error body |
|---|---|
| `/v1/infer/*` | OpenAI: `{"error": {"message", "type", "code", "param"}}`, with the B3OS code in `error.code` |
| `/compat/firecrawl/*` | Firecrawl: `{"success": false, "error", "code", "details"}` |
| `/v1/auth/device/*` | OAuth: `{"error", "error_description"}` |

Errors raised before an operation runs, such as a missing key or an unknown path, use the same shape as the surface you called.

## Reading the OpenAPI document

Each operation carries B3OS extensions that clients and tools can use:

| Extension | Meaning |
|---|---|
| `x-b3os-scope` | The scope the operation needs, or `public`, `authenticated` or `session` |
| `x-b3os-meter` | The usage units it bills (empty when it bills nothing) |
| `x-b3os-stream` | `none`, `sse` or `ws` |
| `x-b3os-timeout-ms` | The longest the request, or the stream, may last |
| `x-b3os-max-body` | The largest request body accepted, in bytes |
| `x-b3os-job` | `true` for operations that create a job, with the job's get, events and cancel operations in `x-b3os-job-ops` |
| `x-b3os-events` | The event types a stream sends |
| `x-b3os-served-by` | `edge` for account operations answered at `beta-api.b3os.org`, `node` for everything else |
| `x-b3os-stage` | `stretch` for operations planned for later in the beta, which answer `501 not_implemented` until they ship |

The document's root also lists the scope catalog, the ID prefixes, the usage units and the beta's default limits.

## Try it

The request panel on each endpoint page sends Try-it requests straight from your browser to `https://beta-api.b3os.org`, with the key you paste; they do not pass through the docs host. The API accepts cross-origin requests that carry a bearer key, from any origin, and lets the page read the `Server-Timing` and `x-request-id` headers.

The panel keeps the key you paste, and a short history of your requests, in this browser's local storage for the docs site until you clear them. Paste a key with only the scopes you need and a spend cap, and revoke it when you are done. The time the panel shows is measured in your browser, network included; `Server-Timing` holds the server's own phases.