Brane AIF Developer API

1. Overview

The Box exposes an OpenAI-compatible gateway at /api/v1. Any tool that speaks the OpenAI Chat Completions protocol — IDE extensions (Continue, Cline), SDKs (openai, @ai-sdk/openai-compatible), n8n, custom apps — can use the Box as its model provider.

2. Base URL

https://<your-box-domain>/api/v1

All endpoints below are relative to this base URL (/api/v1/chat/completions, /api/v1/models, etc.).

3. Authentication

Bearer token on every request:

Authorization: Bearer brn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Issue a key in the admin dashboard under Admin → API Keys (/admin/api-keys). Keys are scoped (chat:completions), can carry a per-key rate limit, and can be revoked at any time. The plaintext key is shown once on creation — store it securely.

4. List models — GET /v1/models

Lists the models the Box exposes. Most SDKs and IDE extensions call this on setup to validate the key and populate a model picker.

curl https://<your-box>/api/v1/models \
  -H "Authorization: Bearer $BRANE_KEY"

{
  "object": "list",
  "data": [
    { "id": "vllm:gemma-4-26b-nvfp4", "object": "model", "created": 1750000000, "owned_by": "local" },
    { "id": "openrouter:anthropic/claude-sonnet-4.5", "object": "model", "created": 1750000000, "owned_by": "openrouter" }
  ]
}

The visible set respects the admin ZDR filter and OpenRouter allowlist. owned_by: "local" marks on-premise vLLM models. Note: the routing mode is not applied here — in local-only mode cloud models may be listed even though every request executes locally.

5. Chat completions — POST /v1/chat/completions

Standard OpenAI Chat Completions. Supports messages and stream with text content. temperature, max_tokens and top_p are accepted but currently not forwarded to the model; image input (image_url) is not yet available (both on the roadmap).

curl https://<your-box>/api/v1/chat/completions \
  -H "Authorization: Bearer $BRANE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vllm:gemma-4-26b-nvfp4",
    "messages": [{ "role": "user", "content": "Refactor this function: ..." }],
    "stream": true
  }'

Streaming returns Server-Sent Events in chat.completion.chunk format, terminated by data: [DONE]. Non-streaming returns a single chat.completion object. The usage field currently uses Vercel AI SDK field names (inputTokens/outputTokens), not the OpenAI format (prompt_tokens/completion_tokens).

6. Sovereignty behaviour

1. The model field is informational only

Guardian picks the actual model solely from the Box's routing mode (local-only, local-preferred, …) and the content of the request: locally the configured box model, in the cloud the admin-configured cloud model. Your requested model is never targeted directly — not even when routing goes to the cloud. The model field in the response names what actually executed; x_brane.model_requested and the X-Brane-Overridden headers reveal a divergence.

2. PII is redacted before cloud

When Guardian routes to a cloud model and the PII policy is anonymize, personal data is replaced with tokens (<PERSON_1>, <EMAIL_1>) before the request leaves the Box, and restored in the response. The cloud model never sees real data. In local-only mode nothing leaves the Box at all — no redaction needed.

7. IDE integration

Continue.dev (VS Code / JetBrains)

~/.continue/config.json:

{
  "models": [
    {
      "title": "Brane AIF (sovereign)",
      "provider": "openai",
      "model": "vllm:gemma-4-26b-nvfp4",
      "apiBase": "https://<your-box>/api/v1",
      "apiKey": "brn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  ]
}

provider: "openai" plus a custom apiBase points Continue at the Box. Chat, explain, and refactor work today.

Cline / Roo

Select the „OpenAI Compatible“ provider, set the Base URL to https://<your-box>/api/v1 and paste the key.

8. Current limitations

Honest scope of what the gateway does not do yet:

9. Errors

OpenAI-style error envelope:

{ "error": { "message": "Invalid API Key", "type": "auth_error" } }

Questions about integrating?

Our team helps you connect your tools.

Contact support