BB Cloud Services

API reference

BB Developers exposes every supported model — Claude, GPT, Gemini, Grok, Mistral and self-hosted Llama — behind a single OpenAI-compatible gateway. If your code already talks to the OpenAI API, point it at the base URL below and set your key.

https://developers.bluebridge.es/api/ai/v1

All requests and responses are JSON. Streaming responses use Server-Sent Events (SSE).

Authentication

Authenticate with a per-tenant gateway key sent as a Bearer token. Create and rotate keys from the console (API Access tab). Keys are prefixed bbc_live_ and are shown in full only once, at rotation.

Authorization: Bearer bbc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Requests without a valid key return 401 Unauthorized.

Chat completions

POST/api/ai/v1/chat

Generates a model response for the given conversation.

Request body

Field	Type		Description
`model`	string	optional	Model id (see Models). If omitted, your pinned default or auto-routing is used.
`messages`	array	required	Conversation turns. Each item is `{ "role", "content" }` with role `system`, `user` or `assistant`.
`temperature`	number	optional	Sampling temperature, `0`–`2`. Defaults to your tenant setting.
`max_tokens`	integer	optional	Max tokens to generate, `1`–`8192`. Defaults to your tenant setting.
`stream`	boolean	optional	When `true`, tokens are streamed as SSE. Defaults to `false`.

Example request

curl https://developers.bluebridge.es/api/ai/v1/chat \
  -H "Authorization: Bearer $BBC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "system", "content": "You are concise." },
      { "role": "user", "content": "What is Blue Bridge Cloud?" }
    ]
  }'

Response

{
  "id": "bbc-a45082d8402c371b",
  "object": "chat.completion",
  "model": "gpt-4o",
  "provider": "OpenAI GPT",
  "live": true,
  "latency_ms": 842.5,
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ]
}

Field	Description
`model`	The model that actually served the request (useful when auto-routing).
`provider`	Human-readable provider label, e.g. `OpenAI GPT`.
`live`	`true` for a real provider call; `false` for a simulated reply (provider key not configured).
`latency_ms`	Server-side generation time in milliseconds.
`choices[].message`	The assistant message.

Streaming

Set "stream": true to receive Server-Sent Events. Each event is adata: line carrying an OpenAI-compatible chat.completion.chunk. The stream ends with a final chunk (finish_reason: "stop") and thendata: [DONE].

data: {"id":"bbc-...","object":"chat.completion.chunk","model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Blue"},"finish_reason":null}]}

data: {"id":"bbc-...","object":"chat.completion.chunk","model":"gpt-4o","choices":[{"index":0,"delta":{"content":" Bridge"},"finish_reason":null}]}

data: {"id":"bbc-...","object":"chat.completion.chunk","model":"gpt-4o","provider":"OpenAI GPT","live":true,"latency_ms":840.1,"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Read incremental text from choices[0].delta.content. The final chunk also carries provider, live and latency_ms.

Model routing

You control which model runs in three ways, in order of precedence:

Explicit — pass model in the request body.
Pinned default — omit model and the request uses the default set in your console.
Auto-route — with auto-routing enabled, the Blue Model Router selects a model per request (short prompts favor the fast/cheap tier; longer or complex prompts favor the high-quality tier).

Models

GET/api/developers/public/catalog

Returns the public model catalogue (no authentication required). Pass any id below as the model field in a chat request.

Model id	Provider	Context	Best for
Loading catalogue…

Errors

Errors use standard HTTP status codes with a JSON body { "detail": "..." }.

Status	Meaning
400	Bad request — unknown `model` id.
401	Missing, malformed or unknown gateway API key.
422	Validation error — e.g. `temperature` or `max_tokens` out of range, or malformed `messages`.
500	Unexpected server error.

Provider-side failures do not raise an HTTP error: the request returns200 with live: false and an explanatory message in the content, so a single provider outage never breaks your integration.

SDKs

Any OpenAI-compatible client works — just override the base URL.

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://developers.bluebridge.es/api/ai/v1",
    api_key="$BBC_API_KEY",
)
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://developers.bluebridge.es/api/ai/v1",
  apiKey: process.env.BBC_API_KEY,
});
const resp = await client.chat.completions.create({
  model: "gemini-2.0-flash",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);

Get your API key