06 api reference

Authentication

Every Exolvra API endpoint lives under /api/v1/ and is authenticated with a bot-scoped API key minted from the dashboard.

Base URL: https://your-exolvra.example (whatever host runs the gateway)
Auth: Authorization: Bearer exo_...
Content type: application/json
Compatibility: /api/v1/chat/completions is OpenAI-compatible — most OpenAI SDKs work by just changing the base_url and api_key

Getting a key

Create a chatbot at /bots/new (or start from a built-in template on the /bots gallery).
Open the bot in edit mode → Section 05 — API Keys → Generate new key.
Copy the plaintext exo_... key. It is shown exactly once. Exolvra stores only a SHA-256 hash.
(Optional) Set the allowed origins so the key only works when called from approved browser origins. Server-to-server callers can leave this empty.

Keys are scoped to a single chatbot. They cannot reach specialist agents, cannot route to CLI providers, and cannot escalate out of cloud-mode capabilities.

Errors

Errors follow the OpenAI shape so SDK error handling works out of the box:

{
  "error": {
    "message": "Invalid or revoked API key.",
    "type": "invalid_request_error"
  }
}

Status	Meaning	Typical causes
401	Missing, invalid, revoked, or expired key	Key not set, typo, revoked in dashboard, past `expires_at`
403	Origin rejected	Browser `Origin` header not on the key’s allowed list
404	Bot missing	The bot bound to the key was deleted, or the session id doesn’t belong to this key
400	Malformed request	JSON parse error, `messages` missing, no user messages present
429	Rate limited	Per-key or provider-level rate limits — backoff and retry
500	Server error	Provider call failed — retry with exponential backoff

CORS

Browser clients: add your site’s origin to the key’s Allowed Origins list in the dashboard. The Exolvra API echoes the matched origin back in Access-Control-Allow-Origin. Requests from origins not on the allowlist get a 403 before the endpoint runs.

Server-to-server callers (Python, Node backend, curl) don’t send an Origin header and bypass CORS — the API key alone is sufficient.

OPTIONS preflight requests (sent automatically by browsers before POST /chat/completions) are handled at the middleware level and return 204 No Content without requiring auth — the real request that follows carries the key.

Security model

Every bot-scoped API key is subject to these non-optional constraints:

Cloud mode is always enforced — the bound bot can use network and memory tools only. Filesystem, shell, and browser tools are unreachable from an API-key session.
CLI providers are blocked — even if the bound bot has a CLI adapter configured, the runtime refuses to route bot-API sessions through external CLIs. This prevents API-key callers from triggering host-process execution.
Specialists cannot be bound — API keys can only point at chatbot agents. Your internal worker agents are unreachable from the public API.
Per-key CORS allowlist — stolen keys still fail when used from an unauthorised browser origin.
Instant revocation — revoking a key in the dashboard invalidates it within the middleware’s 60-second cache TTL.
Per-key audit trail — every request is logged with the key id, bot id, project id, and org id so incidents can be traced precisely.