HTTP API¶

Brama serves one HTTP listener, loopback by default (127.0.0.1:8080, port from brama serve --port, address from BRAMA_BIND_ADDRESS). Every route — including /health — sits behind the transport guard; every route except /health and /readyz additionally requires a bearer. Errors on all routes use the envelope in errors; the example bodies on the pages below were captured from a running 0.2.38 gateway.

This page is the index of the family: it lists every path the router registers and names the page that documents it. The four pages under it hold the detail.

Pages in this family¶

• Transport and identity — which peers the listener accepts, the bearer and organization headers, agent signatures, the request limits every route shares, and the refusal envelope a rejected call receives.
• Inference — the three chat dialects (/v1/chat/completions, /v1/messages, /v1/responses), streaming, and the typed /v1/embeddings and /v1/moderations paths.
• Discovery and subscriptions — /v1/models, /v1/aliases, the subscription pool, plan usage, the account sign-in path, and the shape every usage result answers in.
• Administration and operations — the /v1/admin/* family, including route registry writes and configuration adoption, plus /health, /readyz and /stats.

Route table¶

Every path in the router, the methods it answers, the caller it admits, and the page that documents it.

What holds across the family¶

An alias resolves to exactly one route. The registry maps an alias to its single destination, and when that route refuses the request, the refusal is what the caller receives: no second route is attempted, and Brama adds no elapsed-time cutoff. A declared alias that cannot serve is refused with 503 and code alias_unserviceable, whose details carry the alias state and its route; an alias this gateway does not declare is 404, whose details carry the same two fields. The four states an alias can be in are serving, no_route, capability_absent and routes_file_invalid.

The registry document itself carries exactly three known top-level fields: schema_version, whose value is the number one, deployments and routes. Any other top-level field is refused by the deserializer and the whole document is rejected, so a file written for an older shape is rejected rather than partly read. brama routes migrate rewrites an existing file into this shape and commits it with the same atomic owner-only replacement every other registry write uses.

Where a page shows a response body it was captured from a running gateway, and where it shows a refusal it quotes the sentence the gateway sends. The full error envelope, including type, code, retryable and attempts, is in errors.