API reference¶

Every endpoint of Keera Gateway, generated from its OpenAPI spec. To get started, see The API. Errors are listed in Errors.

One listener serves three APIs, told apart by path:

• /api is the inference API. It speaks the OpenAI and Anthropic formats, so their SDKs work with only a new base URL and an API key.
• /control is the control API, which the panel and the keera command use.
• /sandbox attaches to a sandbox.

Errors share one shape: {"error": {"message", "type", "code"}}.

Inference¶

OpenAI- and Anthropic-shaped requests, behind an API key.

Create a chat completion¶

POST /api/v1/chat/completions

OpenAI's Chat Completions API, for any chat model or router the key may use, whatever provider serves it.

See OpenAI Chat Completions.

Create a text completion¶

POST /api/v1/completions

OpenAI's legacy Completions API, for completion models.

See OpenAI Completions.

Create embeddings¶

POST /api/v1/embeddings

For embedding models.

See OpenAI Embeddings.

Create a message¶

POST /api/v1/messages

Anthropic's Messages API: the same chat models, routers and guardrails as chat completions, in Anthropic's format, translated where the model is not Anthropic's. Errors come in Anthropic's shape, with type: error.

For a subscription model, Claude Code sends the caller's Claude sign-in in Authorization and the Keera key in X-Keera-Key; the gateway passes Anthropic's anthropic-ratelimit-unified-* headers back. See docs/subscriptions.md.

See Anthropic Messages.

Count a message's tokens¶

POST /api/v1/messages/count_tokens

Answered by the gateway from an estimate, never forwarded: forwarding would send the prompt to Anthropic without its filters. The estimate errs high and includes tools and the system prompts the guardrails and routers add. The model is checked as a real request would check it.

See Anthropic Count Message tokens.

Create a response¶

POST /api/v1/responses

OpenAI's Responses API: the same chat models, routers and guardrails, translated where the model is not OpenAI's. On the deployment's key, store is turned off.

See OpenAI Responses.

List models¶

GET /api/v1/models

The models and routers this key may use, in a list both OpenAI's and Anthropic's SDKs read. It is never paged. Locked and decision models are left out.

See OpenAI List models.

Get a model¶

GET /api/v1/models/{alias}

The alias may hold slashes, as in anthropic/claude-sonnet-4-5, escaped or not: the rest of the path is the alias.

See OpenAI Retrieve model.

Warm-up probe¶

HEAD /api/api/hello

Some Anthropic-shaped clients send this before their first request. The path is doubled because they append /api/hello to a base URL that already ends in /api. It always answers 200.

No sign-in needed.

MCP¶

MCP servers, behind the same API keys.

Open the server's event stream¶

GET /api/mcp/{alias}

Passed through to the server, which may answer 405 if it has no stream.

See MCP Streamable HTTP transport.

Send MCP messages¶

POST /api/mcp/{alias}

MCP's Streamable HTTP transport, behind the API key. The body is one JSON-RPC message, or a batch. The gateway lists only the tools the key may call and refuses the others, runs the key's filters over a tool call's arguments, presents the server's own credential and records each call. Everything else is passed through.

A refusal of the gateway's own is a JSON-RPC error with status 200, such as a tool the key may not call, a tool call without an id, or a tool call inside a batch. A key that may call only some tools may send only initialize, ping, tools/*, logging/setLevel and tasks/* other than tasks/list. The client sends Accept: application/json, text/event-stream, as MCP asks.

See MCP Streamable HTTP transport.

End an MCP session¶

DELETE /api/mcp/{alias}

Passed through to the server.

See MCP Streamable HTTP transport.

Probes¶

Liveness, readiness and metrics, for orchestrators and scrapers.

Liveness¶

GET /healthz

No sign-in needed.

Readiness¶

GET /readyz

Ready when Postgres answers. The reason for a failure goes to the log, not the answer.

No sign-in needed.

Prometheus metrics¶

GET /metrics

Metrics span every organisation, so only an operator may read them, or a scraper with the metrics token (KEERA_METRICS_TOKEN) as a bearer token. That token reads this route and nothing else.

Sign in¶

Signing in and out of the control API.

How to sign in¶

GET /control/auth/config

What the panel offers on its sign-in screen, before anybody has signed in.

No sign-in needed.

Start a sign-in¶

GET /control/auth/login

Opened in a browser. It sends the browser to the identity provider, or for a password directory or passkeys to the panel's own form. keera login and Keera Chat add the cli_* parameters, so the sign-in ends at their address with a one-time code for POST /control/auth/cli/token.

A sign-in that cannot start also redirects, to /?sign_in_error=1, with the reason in the keera_sign_in_error cookie.

No sign-in needed.

Finish a sign-in¶

GET /control/auth/callback

Where the identity provider sends the browser back. It only works in the browser that started the sign-in.

No sign-in needed.

Sign in with the operator key¶

POST /control/auth/local

Starts a panel session that grants what the operator key grants.

No sign-in needed.

Redeem a sign-in code for a CLI token¶

POST /control/auth/cli/token

The last step of keera login. The code works once, and only with the PKCE verifier of the process that started the sign-in. Send the token as Authorization: Bearer <token>; GET /control/v1/me says whose it is.

No sign-in needed.

Sign in with a directory password¶

POST /control/auth/password

For an LDAP directory. Attempts are also limited per account, from any address. Must be sent as application/json.

No sign-in needed.

Start a passkey sign-in¶

POST /control/auth/passkey/options

Starts a new sign-in, or with flow continues the one GET /control/auth/login started for keera login. Must be sent as application/json.

No sign-in needed.

Sign in with a passkey¶

POST /control/auth/passkey/sign-in

Each flow works once. Must be sent as application/json.

No sign-in needed.

Start adding a passkey from a set-up link¶

POST /control/auth/passkey/setup/options

Nobody is signed in: the link's token is the credential. Using the options does not use up the link. Must be sent as application/json.

No sign-in needed.

Add a passkey from a set-up link¶

POST /control/auth/passkey/setup

Stores the passkey, uses up the link and signs the person in. Must be sent as application/json.

No sign-in needed.

Read the sign-up in progress¶

GET /control/auth/signup

For a sign-in that matched no organisation, through a provider that allows sign-up. Says who signed in and who invited them.

No sign-in needed.

Create or join an organisation¶

POST /control/auth/signup

Creates a limited organisation with the person as its administrator, or joins the one that invited them, and signs them in. A name another organisation has gets the person's address added.

No sign-in needed.

Sign out¶

POST /control/auth/logout

Ends this session or CLI token. With all=1, ends every session and CLI token of this person, in every organisation.

Me¶

The caller and their own access.

Who the caller is¶

GET /control/v1/me

What the panel loads first. A session gets its CSRF token here.

Switch organisation¶

POST /control/v1/me/org

Moves the caller's session or CLI token to another of their organisations. Choosing one that invited them accepts the invitation. The operator key cannot switch; it names org_id on each request.

My keys, limits and refusals¶

GET /control/v1/access

Only the caller's own keys, even for an administrator, with the limits above each and the refusals of the last week.

Tenancy¶

Organisations, projects, users and passkeys.

List people¶

GET /control/v1/users

An operator who names no organisation sees everyone, by address.

Add a person¶

POST /control/v1/users

Places a person in an organisation before their first sign-in. Needs an administrator of the organisation. A passkey account comes with its first set-up link; an administrator can only create one at the organisation's email domain.

Change a person's role¶

PATCH /control/v1/users/{id}

Needs an administrator of the person's organisation. Not allowed where a directory group decides roles, for an operator, or on yourself. Signs the person out, so the new role applies at once.

Turn a person off¶

POST /control/v1/users/{id}/disable

For someone who left. Revokes their keys, ends their sessions, removes their passkeys and stops their sandboxes. Needs an administrator of their organisation; not for yourself or an operator.

Turn a person back on¶

POST /control/v1/users/{id}/enable

They can sign in again. Their old keys stay revoked. Needs an administrator of their organisation; not for yourself or an operator.

Hand out a passkey set-up link¶

POST /control/v1/users/{id}/passkey-link

Replaces any earlier link. Turns a person who has not signed in yet into a passkey account. Needs an administrator of their organisation, and, for one, an address at the organisation's email domain.

List passkeys¶

GET /control/v1/passkeys

The caller's own, or with user_id someone the caller administers.

Add a passkey to your account¶

POST /control/v1/passkeys

Finishes what POST /control/v1/passkeys/options started. Only for a passkey account, in the panel, within 15 minutes of signing in.

Start adding a passkey to your account¶

POST /control/v1/passkeys/options

For a second device. Only for a passkey account, in the panel, within 15 minutes of signing in; otherwise the code is sign_in_again or forbidden. Takes no body.

Remove a passkey¶

DELETE /control/v1/passkeys/{id}

Anyone may remove their own, but not their last. An administrator may remove anyone's in their organisation, which also signs that person out.

List organisations¶

GET /control/v1/orgs

An operator sees every organisation. Anyone else sees only their own.

Create an organisation¶

POST /control/v1/orgs

Only an operator may. The new organisation starts with the models and sandbox classes of the template files, and a project called default.

Change an organisation¶

PATCH /control/v1/orgs/{id}

Only an operator may. Send at least one field.

Delete an organisation¶

DELETE /control/v1/orgs/{id}

Only an operator may, and not on the organisation they are signed in to. It removes the organisation's projects, users and keys. The request log, billing and audit log stay.

List projects¶

GET /control/v1/projects

Each project comes with its guardrails and its spend this period. An operator who sends no org_id gets every organisation's projects.

Create a project¶

POST /control/v1/projects

Only an administrator of the organisation may.

Rename or describe a project¶

PATCH /control/v1/projects/{id}

Only an administrator of the organisation may. Send at least one field.

Delete a project¶

DELETE /control/v1/projects/{id}

Only an administrator of the organisation may. Every key of the project must be revoked first. Revoked keys stay, with no project.

Keys¶

API keys.

List API keys¶

GET /control/v1/keys

Each key comes with its own guardrails, last use and spend since since.

Issue an API key¶

POST /control/v1/keys

Only an administrator of the organisation may. The secret is in key and is shown only this once. A pending key has no secret yet: the person it is for gets one when they activate it.

Rename an API key¶

PATCH /control/v1/keys/{id}

An administrator may, and so may a member for a key in their own name.

Revoke an API key¶

DELETE /control/v1/keys/{id}

An administrator may, and so may a member for a key in their own name. The key stays listed, revoked, so its usage still has a name.

Rotate an API key¶

POST /control/v1/keys/{id}/rotate

Issues a new key with the old one's project, person, kind and guardrails, and revokes the old one. An administrator may, and so may a member for a key in their own name, but only an administrator may set its lifetime. The secret is in key and is shown only this once.

Activate a pending API key¶

POST /control/v1/keys/{id}/activate

Gives a pending key its secret. The person it is for may, and so may an administrator. The secret is in key and is shown only this once.

Guardrails¶

Limits and rules per organisation, project or key.

Read a guardrail¶

GET /control/v1/guardrails/{scope}/{id}

What this one scope sets on its own. A scope with no guardrail answers an empty one. Anyone in the organisation may read it.

Set a guardrail¶

PUT /control/v1/guardrails/{scope}/{id}

Replaces the scope's guardrail with the body. Only an administrator of the organisation may. On an organisation, only an operator may change allowed_repos; an administrator who leaves it out keeps it.

Read the guardrails that apply¶

GET /control/v1/guardrails/{scope}/{id}/effective

Every level above the scope, and what they combine to, as the gateway combines them. It answers "why is this key refused". Anyone in the organisation may read it.

Filters¶

List filters¶

GET /control/v1/filters

Every member may read it, instructions included. With stats=1 it also says what each filter did in the window.

Create or replace a filter¶

PUT /control/v1/filters/{alias}

Administrators only. A rewrite or gate filter needs model and prompt, and no rules. A pattern filter needs rules, and no model or prompt. See docs/filters.md.

Delete a filter¶

DELETE /control/v1/filters/{alias}

Administrators only. A filter that a router step or a guardrail still uses is refused with 409.

Run a filter over a sample¶

POST /control/v1/filters/{alias}/check

Administrators only. Sends a fixed sample through the filter and shows what came back. A filter that fails still answers 200, with ok false. It runs the filter's model, so it can cost money.

One filter's report¶

GET /control/v1/filters/{alias}/report

Every member may read it. A deleted filter keeps its report; then filter is left out.

Routers¶

List routers¶

GET /control/v1/routers

Every member may read it. With stats=1 it also says what went through each router in the window.

Create or replace a router¶

PUT /control/v1/routers/{alias}

Administrators only. The alias may not be one of the organisation's models (409). A new router is put on the organisation's allow-list, if it has one, unless the list leaves out a model the router reaches; warning then says so. See docs/routers.md.

Delete a router¶

DELETE /control/v1/routers/{alias}

Administrators only. It also comes off the organisation's allow-list. A router that a project's or key's allow-list still names is refused with 409.

Check a router's route steps¶

POST /control/v1/routers/{alias}/check

Administrators only. An instruction step is given sample prompts and shows where each went; the other modes ask their destinations whether they answer. It can cost money. A router with no route step, or no step named by step, answers 400.

One router's report¶

GET /control/v1/routers/{alias}/report

Every member may read it. A deleted router keeps its report; then router is left out.

Models¶

List models¶

GET /control/v1/models

Anyone signed in may read it. Only the organisation's administrators see backends (null for everyone else) and has_api_key. With stats=1 it adds each model's time to first token in the window.

List hosted providers¶

GET /control/v1/providers

The hosted providers this build knows, with their models and prices. Anyone signed in may read it; only an administrator sees endpoint (empty for everyone else).

Create or replace a model¶

PUT /control/v1/models/{alias}

Administrators only. A new model is put on the organisation's allow-list, if it has one. For a provider whose key the deployment holds, the backend and prices are set by the gateway and api_key must be left out. See docs/providers.md.

Delete a model¶

DELETE /control/v1/models/{alias}

Administrators only. It also comes off every allow-list in the organisation. A model a router step still uses is refused with 409.

Check a model works¶

POST /control/v1/models/{alias}/check

Administrators only. Calls the model's own backend with a tool and a question only that tool can answer. A model that fails still answers 200, with ok false. It can cost money.

Send a chat from the panel¶

POST /control/v1/playground/chat

Sends one OpenAI-shaped chat completion with one of the caller's own API keys, named by key_id. It goes through the same data plane as POST /api/v1/chat/completions: that key's guardrails, budgets and usage apply, and the answer is the same, streamed as server-sent events when the body asks for stream. The operator key cannot use it, nor can a subscription key.

MCP servers¶

List MCP servers¶

GET /control/v1/mcp-servers

Anyone in the organisation may read it. Only its administrators see url (empty for everyone else), auth_header and has_api_key.

Create or replace an MCP server¶

PUT /control/v1/mcp-servers/{alias}

Administrators only. See docs/mcp.md.

Delete an MCP server¶

DELETE /control/v1/mcp-servers/{alias}

Administrators only. A server a guardrail's tool allow-list still names is refused with 409.

List tool calls¶

GET /control/v1/tool-calls

Administrators only, for one organisation. Newest first, a page at a time. With summary=1 it adds up the calls of each tool instead, most called first, with no paging.

Connect¶

Setting up clients against this gateway.

List the clients to connect¶

GET /control/v1/connect

The coding agents that can be pointed at this gateway, with their templates, and the gateway address to put in them. Anyone signed in may read it.

Fill in every client's configuration¶

POST /control/v1/connect/render

Renders each client's block for the given models, the default first. No key is sent: a block that holds one carries placeholder instead.

List the caller's own clients¶

GET /control/v1/clients

Which clients called with the caller's own keys in the window, and with which key, newest first. Even an administrator sees only their own. The window is widened to whole days. The operator key has no keys, so it gets an empty list and anonymous.

Reports¶

Usage, requests, sessions, audit and diagnostics.

Check the deployment¶

GET /control/v1/diagnostics

What a deployment is missing, as keera doctor shows it. Nothing is written. An administrator sees their organisation's checks; the deployment's own checks are only for operators.

Count what the deployment has¶

GET /control/v1/setup

For the panel's first-run steps. Without an organisation, an operator gets counts across all of them.

Dashboard figures¶

GET /control/v1/overview

The dashboard in one call. Narrowed to a project, key, person or model, it is that thing's own screen.

Traffic between clients and models¶

GET /control/v1/map

The deployment as a picture: the clients that called, every model of the organisation, and the traffic between them. A member sees only the traffic of their own keys.

Usage report¶

GET /control/v1/usage

Requests, tokens and cost per group. Over more than two days it counts whole days, and from and to say so.

Audit log¶

GET /control/v1/audit

Who changed what, newest first. Administrators only. Without from, to or since it has no time window.

Request log¶

GET /control/v1/requests

One row per inference request, whatever happened to it. An administrator reads the whole organisation's; a member only the requests made with their own keys.

Request log, live¶

GET /control/v1/requests/stream

The rows GET /control/v1/requests returns, narrowed the same way, as they are written. The response stays open.

Each batch is an event named requests whose data is a JSON object:

• data: the new rows, newest first, at most 200 (RequestLogEntry).
• outcomes: the counts over the window since gives (RequestOutcomes).
• next_after: the newest id sent. Pass it as after to resume.
• project_names, key_names, user_names, user_full_names: only when a row names something the earlier labels did not.

An idle stream sends a : keepalive comment every 25 seconds. It ends when the server shuts down; reconnect with after.

Sessions¶

GET /control/v1/sessions

The request log grouped into tasks. A member sees only the sessions of their own keys. See docs/sessions.md.

One session¶

GET /control/v1/sessions/{id}

One task from start to end. A member sees it only if every request in it was made with their own keys.

Billing¶

Monthly bill¶

GET /control/v1/billing

One month of use of the deployment's own provider keys, per organisation and provider model, at list price. Administrators only. See docs/billing.md.

Credit account¶

GET /control/v1/billing/account

The organisation's credit, its settings and its latest payments. Administrators only. It first looks up payments started in the last hour, so one just paid shows at once. On a deployment that takes no payments, it answers only {"payments": false}.