API overview

Cocobox exposes OpenAI-shaped, Anthropic-shaped, and MCP endpoints under a single sk-coco-* key. Here's how it all fits together.

The Cocobox API gives external clients the same AI capabilities the Cocobox app uses internally — with one key, one base URL, and three wire formats:

• OpenAI Chat Completions at POST /v1/chat/completions — used by opencode and any OpenAI-shape SDK.
• Anthropic Messages at POST /v1/messages — used by the official Claude Code CLI and any Anthropic SDK.
• Model Context Protocol (Streamable HTTP) at POST /v1/mcp — used by GitHub Copilot in VS Code, Cursor, Zed, opencode, and Claude Code as a tool transport.

Pick whichever shape your client speaks — they all charge the same per-request credits, log to the same audit trail, and use the same API key.

Base URL

https://api.cocobox.io/v1

There is one base URL. There are no regional variants (yet). All traffic is HTTPS-only — plain HTTP requests are rejected at the load balancer.

Authentication

Every request must include an API key in either form:

Authorization: Bearer sk-coco-…

or

x-api-key: sk-coco-…

Keys start with sk-coco- followed by 32 hex characters. They’re created in the app under Settings → API keys or programmatically (see API keys).

The full key is shown once at creation, then never again. We store only a SHA-256 hash; if you lose a key, rotate it.

See Authentication for header details, scoping, and rotation.

Versioning

The API is versioned at the URL prefix (/v1). We will add /v2 only for breaking wire-format changes. Additive changes (new fields, new tools, new models) ship under /v1 without a version bump.

When we change something on /v1, we:

• announce in the Changelog at least 30 days in advance for additive changes,
• announce at least 90 days in advance for any deprecation, with a reasonable migration window.

Rate limits

Soft limits per API key:

• 50 requests / minute burst.
• 5 concurrent streaming requests.
• Per-key request budget — opt-in cap you set when creating the key (e.g. max 10,000 requests). After that, the key starts returning 429.

Limit headers are returned on every successful response:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1735689600

See Rate limits for the full policy.

Errors

All errors return a JSON body:

{
  "status": 401,
  "error": "unauthorized",
  "message": "Invalid or missing API key.",
  "request_id": "req_01HF…"
}

request_id is what to send when filing a support ticket. See Errors.

Models

Each request must specify a model. Cocobox accepts both friendly aliases (tambor, prisma, sonnet, opus) and the full provider model id. Different models cost different credits per request.

See Models and Reference → Supported models.

Tools

The MCP endpoint exposes a catalog of tools the model can call (e.g. sql_run, sql_describe). On the OpenAI / Anthropic surfaces, tools are passthrough — your client picks them up via MCP and orchestrates the loop.

See API → MCP server and Reference → MCP tools.

Quick request

A minimal Chat Completions call:

curl https://api.cocobox.io/v1/chat/completions \
-H "Authorization: Bearer sk-coco-…" \
-H "Content-Type: application/json" \
-d '{
  "model": "tambor",
  "messages": [
    { "role": "user", "content": "Write a SQL query that returns the 10 most recent orders." }
  ]
}'

const r = await fetch('https://api.cocobox.io/v1/chat/completions', {
method: 'POST',
headers: {
  'Authorization': `Bearer ${process.env.COCOBOX_API_KEY}`,
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  model: 'tambor',
  messages: [{ role: 'user', content: 'Write a SQL query that returns the 10 most recent orders.' }],
}),
});
const json = await r.json();
console.log(json.choices[0].message.content);

import os, requests

r = requests.post(
  "https://api.cocobox.io/v1/chat/completions",
  headers={"Authorization": f"Bearer {os.environ['COCOBOX_API_KEY']}"},
  json={
      "model": "tambor",
      "messages": [
          {"role": "user", "content": "Write a SQL query that returns the 10 most recent orders."}
      ],
  },
)
print(r.json()["choices"][0]["message"]["content"])

What to read next

• Authentication — header forms, scoping, rotation.
• API keys — create, list, rotate, revoke.
• Models — the full menu and credit costs.
• MCP server — Streamable HTTP transport, sessions, tools.