Quickstart
OpenPike is a gateway in front of the LLM providers you already pay. Your agents send requests to OpenPike with an OpenPike key; OpenPike checks budgets, forwards the request with your own provider key, streams the response back and records the spend.
Five minutes to the first request
- Sign in to the dashboard and add a provider key on the Providers page. It is encrypted and never shown again.
- On the Keys page, create a virtual key for your agent, for example with the tag
agent=pr-reviewer. Copy it: the full key is shown once. - Point your SDK at OpenPike and use a
provider/modelname.
OpenAI SDKs (Python)
from openai import OpenAI
client = OpenAI(base_url="https://api.openpike.dev/v1", api_key="opk_live_...")
client.chat.completions.create(
model="deepseek/deepseek-chat",
messages=[{"role": "user", "content": "Hello"}],
extra_headers={"x-openpike-tags": "agent=pr-reviewer"},
)
OpenAI SDKs (TypeScript)
const client = new OpenAI({
baseURL: "https://api.openpike.dev/v1",
apiKey: process.env.OPENPIKE_KEY,
defaultHeaders: { "x-openpike-tags": "agent=pr-reviewer" },
});
Anthropic SDKs
import anthropic
client = anthropic.Anthropic(base_url="https://api.openpike.dev", api_key="opk_live_...")
client.messages.create(
model="anthropic/claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
curl
curl https://api.openpike.dev/v1/chat/completions \
-H "Authorization: Bearer $OPENPIKE_KEY" \
-H "Content-Type: application/json" \
-H "x-openpike-tags: agent=pr-reviewer,env=prod" \
-d '{"model": "deepseek/deepseek-chat", "messages": [{"role": "user", "content": "Hello"}]}'
Base URL and keys
The gateway is at https://api.openpike.dev. It speaks three formats:
| Endpoint | Format |
|---|---|
POST /v1/chat/completions | OpenAI chat completions, streaming included |
POST /v1/messages | Anthropic messages, streaming included. anthropic-version and anthropic-beta pass through |
POST /v1/systemone | TypeSafe System One decisions (Jev): { model, state, questions } |
GET /v1/models | Models from every provider you have a key for, in OpenAI list format |
Send your OpenPike virtual key as Authorization: Bearer opk_live_... or as x-api-key: opk_live_..., so OpenAI and Anthropic SDKs work unchanged. Virtual keys are stored only as hashes; revoking one takes effect on its next request. Request bodies pass through untouched, unknown fields included.
Model names
Models are addressed as provider/model: the provider slug, then the provider's own model ID, which is sent upstream unchanged. Everything after the first slash goes upstream.
deepseek/deepseek-chat
anthropic/claude-sonnet-5-5
typesafe/jev-1.13.0
openrouter/openai/gpt-5
Each endpoint only routes to providers that speak its format natively: an Anthropic model on /v1/chat/completions returns unsupported_format.
Tags
Tags attribute spend and scope budgets. A virtual key carries tags, and each request can add or override them with the x-openpike-tags header: comma-separated key=value pairs, at most 10, keys and values at most 64 characters.
x-openpike-tags: agent=reviewer,project=checkout,env=prod
The agent tag is special in the dashboard: the Agents page groups spend by it and lets you pause one agent with a click.
Aliases and fallbacks
Define an alias on the Routing page and use it as the model name: openpike/<name>. An alias is a list of up to 10 provider/model targets for one endpoint, tried in order (ordered) or cheapest first by the price table (cheapest_first).
- The gateway falls back to the next target on a 429, a 5xx, a network error, or an error saying the model does not exist.
- Fallback only happens before the first byte reaches your client. Once a response starts streaming, it is never retried.
- At most 3 attempts per request. Targets whose provider has no key in the workspace are skipped.
- The response headers
x-openpike-modelandx-openpike-attemptstell you which target served it.
Budgets and loop detection
Budgets cap spend for the whole workspace, one virtual key, or one tag such as agent=reviewer, per hour, day or month (calendar periods in UTC). A soft limit sends an alert; a hard limit blocks requests with 429 budget_exceeded until the period resets or you raise it. Spend is known only after a response, so the request that crosses a hard limit completes and the next one is blocked.
Loop detection pauses a key or tag when its requests or spend per minute cross a limit, with 429 loop_detected and a retry-after header. You can also pause and resume any agent or key from the dashboard; paused requests get 429 scope_paused. Changes take effect on the next request.
Alerts for soft limits, hard limits and loop pauses go to email and Slack, configured on the Alerts page.
Response headers
| Header | Meaning |
|---|---|
x-openpike-request-id | Request ID, also shown in Logs |
x-openpike-provider | Provider that served the request |
x-openpike-model | The provider/model that served it (differs from the request for aliases) |
x-openpike-attempts | Upstream attempts, 1 without fallback |
retry-after | On a 429 from OpenPike: seconds until you can retry |
server-timing | gate;dur=..., time spent on the budget check |
Error codes
Errors use the native shape of each endpoint, so SDKs parse them. Chat completions and System One return { "error": { "type": "openpike_error", "code", "message", "request_id" } }; messages return Anthropic's { "type": "error", "error": { "type", "message" } }.
| HTTP | Code | When |
|---|---|---|
| 401 | invalid_virtual_key | Missing, unknown or revoked virtual key |
| 400 | invalid_request | Body is not a JSON object |
| 400 | invalid_tags | Tags break the limits |
| 400 | invalid_model | Not provider/model, unknown provider, or unknown alias |
| 400 | unsupported_format | The provider does not speak this endpoint's format |
| 403 | provider_disabled | Provider is not enabled |
| 424 | missing_provider_key | Your workspace has no key for that provider |
| 429 | budget_exceeded | A hard budget is used up for this period |
| 429 | loop_detected | A loop limit paused this key or tag |
| 429 | scope_paused | Paused from the dashboard |
| 429 | too_many_auth_failures | Too many invalid keys from your address this minute |
| 502 | upstream_unreachable | The provider could not be reached |
| other | upstream_error | The provider returned an error: its status and message, with anything that looks like a key removed |
What we store
Provider keys are encrypted with a per-workspace key and decrypted only in memory for one request. Prompts and responses are never stored: OpenPike keeps request metadata only (model, tokens, cost, latency, status and tags) for spend reporting. Report security issues to security@openpike.dev.