API reference

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. 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. Three streams also accept a single-use stream ticket for browsers.

Conventions

• Objects carry id (a prefixed ID), 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: 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; 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.

Errors

Native endpoints return RFC 9457 problems (application/problem+json) with a stable code; the errors page 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.