BBramaDocs

Brama core contract: request surface

Wire formats and streaming

This page fixes the outer edge of the core contract: which concerns core owns, which of them integrations are allowed to implement, the three chat request formats Brama accepts, and the one rule that governs a streamed answer.

Core versus integrations

Core consists of:

  • secure HTTP ingress and exact client/agent binding;
  • provider-neutral model, message, tool, usage, and error contracts;
  • canonical route, alias, selector, billing-target, and bounded-attempt policy;
  • final-use capability redemption seams;
  • append-only retirement and quality state;
  • build identity, health, statistics, CLI, and read-only MCP boundaries.

Provider protocols, models.dev, Skarbiec transport, the entitlements router, host deployment, and external model services are integrations. They may implement a core seam, but they must not redefine client identity, ownership, limits, state authority, or public error semantics. The route registry is a core artifact for the same reason: it names one destination per alias, and brama routes migrate is the supported way to bring an operator's existing document to that shape.

Accepted wire formats

Three chat request formats are accepted and are one workflow, not three: OpenAI chat completions at POST /v1/chat/completions, Anthropic Messages at POST /v1/messages, and OpenAI Responses at POST /v1/responses. The format decides only how a request is read and how an answer is written. Client identity, model allowlist, alias resolution, selector semantics, caller-scoped ownership, attempt bounds, ledger accounting, and the error contract are identical across all three, and every one of them requires a canonical provider/model route or a supported selector: no format is permitted to guess a provider from a bare vendor model name.

Inbound translation keeps only what the provider-neutral request can hold. Stop sequences, cache-control hints, reasoning options, stored-response identifiers, and non-function tool types are accepted and dropped rather than approximated. Outbound translation states only what the provider reported: a stream whose provider published no token meter yields no token numbers.

Aliases on the request surface

An alias named in any of the three formats resolves to exactly one route. The registry holds one destination per alias, so there is no ordered list of spare destinations to walk and no second route behind the first. When the resolved route refuses, that refusal is the answer the caller receives, in the caller's own dialect. A declared alias that cannot serve answers 503 alias_unserviceable and carries details.state and details.route; an undeclared alias answers 404, whose details carry the same two fields. Public workflows describes the four alias states and how each one is reached.

Streaming

Any of the three chat formats streams when its request asks for it. The response is text/event-stream in the caller's own dialect: chat.completion.chunk frames closed by data: [DONE], Anthropic message_start, content_block_*, message_delta and message_stop events, or response.* events closed by response.completed.

Streaming requires a route this gateway owns a protocol for. A model reached only through the shared catalogue is buffered by construction, so asking to stream one is refused as 400 invalid_request before any provider is contacted, rather than reported as a provider failure.

The commit boundary

One rule governs it. A stream is either committed or it is not, and the boundary is the provider's response status:

  • before commit, candidate and credential counts and the one forced OAuth refresh remain bounded. A refusal is an ordinary error document because the caller has received nothing;
  • after commit, nothing is retried. A failed connection or a provider that ends without its terminal event ends the caller's stream without one too. Brama does not stop a generation merely because no bytes arrived for a while, and does not continue it on another credential: a second attempt would duplicate both cost and emitted text.

Credential rotation before the first streamed byte is rotation across credentials for the one route the request named. It never reaches a second route for an alias, and it never crosses into another account's inventory.

A caller that receives no terminal event holds an incomplete generation. It may start a new request; Brama will not have done so on its behalf.

Subscription spend is recorded once per stream, whether it completed, failed mid-flight, or was abandoned by the caller: the tokens the provider reported and the plan windows its headers carried are ledger facts regardless of who stopped listening.

Where to go next

  • Public workflows — the four ways a request reaches a provider, and how task-quality evidence is collected.
  • State and failures — ownership, the error envelope, attempt bounds, and resource limits.
  • HTTP API — the endpoint-by-endpoint reference for these three formats.