Documentation

Quick start

Brain Orchestra implements the OpenAI /v1/chat/completions format. If you already use the OpenAI SDK or any OpenAI-compatible client, point it at https://api.brainorchestra.ai and you're done.

curl https://api.brainorchestra.ai/v1/chat/completions \
  -H "Authorization: Bearer bo_live_YOUR_API_KEY" \
  -H "X-User-Id: alice@acme.com" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "Hello from Brain Orchestra" }
    ],
    "stream": true
  }'

Two headers are required on every request: Authorization: Bearer <api_key> and X-User-Id: <email_or_id>. The user ID is how BO attributes requests to end-users in your audit trail — pass the email of whoever is making the request on your side.

Model selection

The model field accepts three kinds of values:

• A specific BO model name — claude-sonnet, gpt-4o-mini, mistral-large, gemini-flash, and so on. Routes directly to that model.
• auto — BO picks the highest-scoring available model for your project's territorial tier, based on real-time health data and cost optimization.
• A compliance shorthand — eu-strict, eu-cloud, eu-sweden. BO picks the best model qualifying for that tier. Optional size suffix: eu-strict:small.

Territorial tiers

Every project has a territorial tier that controls which models (and which physical regions) are allowed to serve your requests. Territorial tier is enforced — customer-asserted compliance with a full audit trail.

You can tighten the tier per request (never loosen it) via routing_preferences.compliance:

curl https://api.brainorchestra.ai/v1/chat/completions \
  -H "Authorization: Bearer bo_live_YOUR_API_KEY" \
  -H "X-User-Id: alice@acme.com" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [...],
    "routing_preferences": {
      "compliance": "eu_strict"
    }
  }'

If the explicit modeldoesn't qualify for the requested tier, BO rejects the request with 400 model_not_compliant and returns the list of compliant alternatives so you can retry. This is a hard constraint — we will never silently route a request to a provider that violates the tier you asked for.

PII protection

When enabled, Brain Orchestra routes prompts through a Presidio-based PII gateway before any provider call. Detected entities are pseudonymized (or redacted) server-side; the provider sees only the scrubbed version. Token mappings live in a session-scoped vault and are purged after the request completes.

Six languages supported: English, French, German, Italian, Swedish, Spanish. Custom recognizers for Swedish personnummer and IBAN.

curl https://api.brainorchestra.ai/v1/chat/completions \
  -H "Authorization: Bearer bo_live_YOUR_API_KEY" \
  -H "X-User-Id: alice@acme.com" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [
      {
        "role": "user",
        "content": "My name is Karl Karlsson. What's 2+2?"
      }
    ],
    "pii_policy": {
      "enabled": true,
      "sensitivity": "medium",
      "action": "pseudonymize"
    }
  }'

The audit log records pii_policy_received, pii_processed, pii_entities_detected, and pii_redactions_applied on every request that carries a pii_policy field — so you can prove the feature ran by querying /v1/data/audit.

Audit trail

Every request produces a durable audit record — success, failure, rate-limit rejection, PII fail-closed, compliance mismatch, and everything in between. Audit records are written via a transactional outbox pattern and advance through a documented state machine, so even mid-stream crashes can't leave a request stuck in an invisible state.

Query the audit log programmatically via GET /v1/data/audit, filter by actor_id, model, or status, and get back the full metadata: provider, resolved model, effective tier, cost, tokens, data region, and pricing provenance (what price was in effect at request time).

Advanced features

• Embeddings — POST /v1/embeddings. Same tier-aware routing as chat completions, with EU-owned alternatives (mistral-embed, mistral-codestral-embed) for strict sovereignty.
• MCP server — Model Context Protocol JSON-RPC 2.0 at POST /v1/mcp. Compatible with Claude Desktop, Cursor, and any MCP client. Tools: search_audit_logs, list_traces, get_model_health, and more.
• Traces — governed operations for agentic AI. Create a trace with a budget, depth limit, and allowed model list; every LLM call within the trace is gated by the operation contract and logged as a span. See POST /v1/traces.
• Data API — seven read-only endpoints at /v1/data/* for SIEM integration, custom dashboards, and automated reporting. API-key auth only (no actor token required).
• Billing API — GET /v1/billing/balance, /usage, and /reconciliations for programmatic access to spend data, scoped to the calling project.

Pricing

Brain Orchestra uses a prepaid balance model with a 5% platform fee on token usage through managed keys. Top up your balance via the dashboard (EUR / USD / SEK); each request atomically deducts the provider cost plus 5% from your balance, with full per-request transparency in the audit log. Monthly reconciliation against the actual provider invoice.

Bring your own provider API keys (BYOK) and the 5% fee is waived entirely — BO acts purely as the governance + audit layer. You can mix BYOK and BO-managed keys per project, and every request is tagged with its key source so billing is unambiguous.

Plans:

• Free — 1,000 requests/month, unrestricted tier only
• Trial — 30 days of Pro access (100,000 requests/month, all tiers). Card required at signup so the trial flips to Pro automatically when it ends.
• Pro — €79 / $79 / 899 kr per month, 100,000 requests/month, all tiers including EU-sovereign (eu_strict, eu_cloud, eu_sweden)
• Enterprise — custom pricing, unlimited requests, negotiable convenience fee, SLA, dedicated support

Subscription tiers exist alongside the per-token fee, not instead of it — Pro unlocks higher request quotas and the EU-sovereign tiers, but the 5% on managed-key usage applies to every plan. Enterprise contracts can negotiate the convenience fee.