Integration contracts¶

An integration is a boundary Brama depends on but does not own: a model provider's HTTP API, the public models.dev catalog, the Skarbiec capability broker, the entitlements router, GitHub Releases together with the host service manager, and Weles reauthentication. Brama owns the normalized contract at that boundary and nothing behind it.

Integrations extend the stable core in CORE.md. They do not redefine client identity, subscription ownership, routing limits, state authority, or public error semantics.

This index states what every integration is, in one row each, and links the four pages that carry the contracts.

Pages¶

Providers

Model providers

Registering an existing model bearer, the adapter boundary, capability declaration, and the provider contract itself: identity, reliability, compatibility, disablement.

Catalog

models.dev catalog

Public provider and model metadata: origin, cache, validation, and the exact limits of what advisory metadata may authorise.

Secrets

Skarbiec and entitlements

Final-use capability redemption over the Unix socket, and the entitlements router that discovers the shared subscription pool and persists credentials.

Operations

Publication and health

GitHub Releases and versioned host installation, what /health and /stats prove, integration error codes, and the change gate.

Summary¶

Integration	Protocol	Identity	Current capability	Runtime owner
OpenAI, OpenRouter, Groq, Mistral, xAI, DeepSeek, Cerebras, Fireworks, Together, NVIDIA, Moonshot, Z.AI, Qwen, Hugging Face, Featherless, Venice, Novita, Synthetic, Kimi	OpenAI Chat compatible	direct API capability, account-owned API key, or agent subscription	buffered or streamed chat; tools where advertised; Kimi streams publish no token meter	Brama operator / credential owner
Anthropic and Claude Code	Anthropic Messages	direct API capability, account-owned Anthropic key, or pooled OAuth subscription	buffered or streamed chat and tool use	Brama operator / credential owner
Codex	OpenAI Responses event stream	account-owned or pooled OAuth subscription	streamed to the caller, or the same event stream consumed internally for a buffered answer; tool calls either way	subscription owner
Google catalog providers	GenerateContent	account-owned or deployment API capability	buffered chat and tools where advertised	credential owner
OpenAI embeddings	OpenAI embeddings	direct OpenAI capability	alias-only typed endpoint	Brama operator
OpenAI moderation	OpenAI moderation	direct OpenAI capability	alias-only typed endpoint	Brama operator
models.dev	HTTPS JSON catalog	no credential	public metadata and protocol discovery	models.dev; cached by Brama
Skarbiec capability broker	`skarbiec.redeem.v1` over Unix socket	Brama workload Ed25519 proof	final-use bounded secret redemption	Skarbiec operator
entitlements router	local process/CLI	local vault authorization	live subscription list, credential put, capability service	Skarbiec operator
GitHub Releases and host service manager	HTTPS assets plus operator-owned installation	GitHub publisher and host operator	immutable publication and versioned host installation	Brama release owner / deployment operator
Weles reauthentication	dedicated HTTPS operation	finite Brama reauth token	refresh of the accepted runtime identity only	Weles operator

Routing is not an integration¶

Which provider serves an alias is Brama's own decision, recorded in the route registry document. An alias names exactly one destination route. When that route refuses a request, the refusal is what the caller receives: no second route is attempted. Completion and failures follow the core request contract, not a gateway clock.

The registry document carries three known top-level fields — the schema version, deployments and routes — and the schema version is the number one. routes maps an alias to its single destination. An unknown top-level field is refused by the deserializer, so a document carrying anything else is rejected whole. An operator moves an existing file to this shape with brama routes migrate, which keeps only the known fields, validates the result, commits it with the same atomic owner-only replacement every other registry write uses, and prints the document. Running it twice changes nothing the second time.

The alias surfaces are PUT and DELETE /v1/admin/routes, GET /v1/aliases and brama aliases. A declared alias that cannot serve answers 503 alias_unserviceable, carrying its state and its route in details; see Errors.