Guide

Model Gateway

Route requests to any LLM provider through a single endpoint. Bring your own keys, set budgets, and track usage — with or without Cadreen's intelligence layer.

Three ways to use the gateway

The gateway is the routing layer. Cadreen is the intelligence layer. You can use the gateway alone, or stack Cadreen on top.

Gateway endpoint (no Cadreen)

Pure routing. Pick a model, get a response. No governance, no memory, no intelligence layer.

POST/api/v1/cadreen/gateway/responses

When to use: You want model routing, BYOK, and budgets — without Cadreen's governance layer.

Completions endpoint (with Cadreen)

OpenAI-compatible. Cadreen adds governance, memory, traces, and self-healing on top.

POST/api/v1/cadreen/chat/completions

When to use: You want the full intelligence layer — rules, memory, decision logs, auto-learning.

Intent endpoint (Cadreen-native)

Cadreen decides which model to use. Full pipeline: governance, memory, tool execution.

POST/api/v1/cadreen/intent

When to use: You want Cadreen to handle everything — model selection, routing, governance, execution.

Note

The gateway endpoint uses the model field to pick the provider and model. The completions endpoint ignores model — Cadreen decides internally.

Quick start

curl

curl -X POST https://api.cadreen.com/api/v1/cadreen/gateway/responses \
  -H "Authorization: Bearer sk_cadreen_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": [{"type": "message", "role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'

Python

import requests

response = requests.post(
    "https://api.cadreen.com/api/v1/cadreen/gateway/responses",
    headers={"Authorization": "Bearer sk_cadreen_..."},
    json={
        "model": "anthropic/claude-sonnet-4-20250514",
        "input": [{"type": "message", "role": "user", "content": "Hello"}],
        "max_tokens": 100,
    },
)
print(response.json())

TypeScript

const response = await fetch(
  "https://api.cadreen.com/api/v1/cadreen/gateway/responses",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_cadreen_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "openai/gpt-4o",
      input: [{ type: "message", role: "user", content: "Hello" }],
      max_tokens: 100,
    }),
  }
);
const data = await response.json();

Note

No model? The gateway uses your default routing policy. Pin a model to bypass routing — budget and key checks still apply.

Use with the OpenAI SDK

Already using the OpenAI SDK? Point it at Cadreen's gateway. No code changes needed — just change the base URL.

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk_cadreen_...",
    base_url="https://api.cadreen.com/api/v1/cadreen/gateway/openai",
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk_cadreen_...",
  baseURL: "https://api.cadreen.com/api/v1/cadreen/gateway/openai",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

Note

The gateway is also compatible with the Anthropic SDK, LangChain, and any client that supports a custom base URL. Just point it at the gateway endpoint.

Supported providers and models

Use the format provider/model in the model field. The gateway supports 150+ models with live pricing:

Provider	Models

Note

Not sure which model to use? Omit model and the gateway's routing policy selects one for you. Or use Cadreen's /chat/completions endpoint — Cadreen picks the best model automatically.

Bring your own keys (BYOK)

Add your own provider API keys. Requests through your keys use your provider account directly — no markup, no middleman.

Add a key via dashboard

Go to Dashboard → How it routes → Add key
Select provider (e.g., OpenAI)
Paste your API key

Key behavior:

Scoped to BYOK_ONLY — never falls back to managed credentials
If your key is invalid, request fails with provider_credentials_missing
Multiple keys supported — one per provider

Note

BYOK usage has no markup. Managed routing (Cadreen's keys) has a configurable workspace markup.

Budgets

Set per-workspace spending limits. Choose soft limits (warn when exceeded) or hard limits (stop when exceeded).

Set a budget via dashboard

Go to Dashboard → How it routes → Budget
Amount: $50.00
Period: Monthly
Enforcement: Hard (stops when exceeded)

Budget behavior:

Checked AFTER each request completes (the request that pushes you over succeeds)
Hard limit: next request returns 402 budget_exceeded
Soft limit: request proceeds, warning appears in dashboard
Both BYOK and managed usage count toward the budget

Usage tracking

Track spending across providers, models, and time periods. See where your money goes.

Fetch usage via API

curl -H "Authorization: Bearer sk_cadreen_..." \
  "https://api.cadreen.com/api/v1/maas/gateway/usage?start=2026-07-01&end=2026-07-31"

Response

{
  "byok_spend": 45.20,
  "managed_spend": 12.50,
  "total": 57.70,
  "by_model": {
    "openai/gpt-4o": 30.00,
    "anthropic/claude-sonnet-4-20250514": 15.20
  }
}

Streaming

Set "stream": true to receive SSE. The format matches OpenAI's streaming.

Streaming response

data: {"type":"response.output_text.delta","delta":"The "}
data: {"type":"response.output_text.delta","delta":"weather..."}
data: [DONE]

Error handling:

Before stream opens — HTTP status with error JSON (budget exhausted, bad request)
After stream opens — in-band error frame: {"object":"response.error","error":{...}}
Success — ends with {"object":"response.done"}

Error reference

HTTP	Type	When
`400`	`invalid_request_error`	Malformed request or embedded routing not enabled
`401`	`authentication_error`	Missing or invalid API key
`402`	`budget_exceeded`	Hard budget exhausted
`403`	`permission_error`	Customer is inactive or deleted
`404`	`not_found_error`	Unknown customer or missing provider credentials
`503`	`unavailable`	Configuration could not be read — retry

When to use which endpoint

I want to	Use	Why
Route to a specific model	`/gateway/responses`	Pin `model`. No governance. Pure routing.
Use my own API keys	`/gateway/responses`	BYOK. Your budget. No markup.
Get an answer with rules enforced	`/chat/completions`	OpenAI-compatible. Adds governance, memory, traces.
Let Cadreen pick the best model	`/intent`	Full pipeline. Model selection, governance, execution.
Just use Cadreen as an OpenAI replacement	`/chat/completions`	Drop-in. Same API. Add governance for free.

Next steps

Model Provider Guide — The completions endpoint (OpenAI-compatible, with Cadreen)
Connect a Tool — Set up your first integration
Gateway Dashboard — Manage keys, budgets, and usage

curl -X POST https://api.cadreen.com/api/v1/cadreen/gateway/responses \ -H "Authorization: Bearer sk_cadreen_..." \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-4o", "input": [{"type": "message", "role": "user", "content": "Hello"}], "max_tokens": 100 }'

import requests response = requests.post( "https://api.cadreen.com/api/v1/cadreen/gateway/responses", headers={"Authorization": "Bearer sk_cadreen_..."}, json={ "model": "anthropic/claude-sonnet-4-20250514", "input": [{"type": "message", "role": "user", "content": "Hello"}], "max_tokens": 100, }, ) print(response.json())

const response = await fetch( "https://api.cadreen.com/api/v1/cadreen/gateway/responses", { method: "POST", headers: { "Authorization": "Bearer sk_cadreen_...", "Content-Type": "application/json", }, body: JSON.stringify({ model: "openai/gpt-4o", input: [{ type: "message", role: "user", content: "Hello" }], max_tokens: 100, }), } ); const data = await response.json();

from openai import OpenAI client = OpenAI( api_key="sk_cadreen_...", base_url="https://api.cadreen.com/api/v1/cadreen/gateway/openai", ) response = client.chat.completions.create( model="anthropic/claude-sonnet-4-20250514", messages=[{"role": "user", "content": "Hello"}], ) print(response.choices[0].message.content)

import OpenAI from "openai"; const client = new OpenAI({ apiKey: "sk_cadreen_...", baseURL: "https://api.cadreen.com/api/v1/cadreen/gateway/openai", }); const response = await client.chat.completions.create({ model: "openai/gpt-4o", messages: [{ role: "user", content: "Hello" }], }); console.log(response.choices[0].message.content);

Provider

Models

HTTP

Type

When

400

invalid_request_error

Malformed request or embedded routing not enabled

401

authentication_error

Missing or invalid API key

402

budget_exceeded

Hard budget exhausted

403

permission_error

Customer is inactive or deleted

404

not_found_error

Unknown customer or missing provider credentials

503

unavailable

Configuration could not be read — retry

I want to

Use

Why

Route to a specific model

/gateway/responses

Pin model. No governance. Pure routing.

Use my own API keys

/gateway/responses

BYOK. Your budget. No markup.

Get an answer with rules enforced

/chat/completions

OpenAI-compatible. Adds governance, memory, traces.

Let Cadreen pick the best model

/intent

Full pipeline. Model selection, governance, execution.

Just use Cadreen as an OpenAI replacement

/chat/completions

Drop-in. Same API. Add governance for free.