API reference

Authentication & API keys

Bearer keys, key hygiene, rotation, and revocation.

Bearer authentication

Most /api/v1/* endpoints expect an HTTP header:

Authorization: Bearer sk-runaii-<48 hex chars>

Two endpoints are public and need no key: GET /api/v1/models (the catalog) and GET /api/v1/status (the serverless lifecycle board) — both exist so a client can discover models and poll boot state before it has a key.

Keys are generated in Console → API Keys, shown once at creation, and stored hashed (HMAC-SHA256 with a server-side pepper) — nobody, including us, can read them from the database.

x-api-key (Anthropic SDK clients)

Anthropic-dialect calls (POST /api/messages, aliased at /api/v1/messages when your SDK appends the path) accept the native Anthropic header instead:

x-api-key: sk-runaii-<48 hex chars>
anthropic-version: 2023-06-01

Base URL for Anthropic SDKs: https://api.runaii.cloud/api. The Responses API (POST /v1/responses) uses the same Bearer header as everything else under /api/v1/*. It is the same key and the same account — per-key rate limits, daily caps, and billing apply identically on all three dialects.

Key properties

Scoped to your account — a key can never see another account's usage or balance
Per-key authority scopes — at creation a key gets inference (API/model spend) and/or deployments (paid GPU control). A deployments-only key is refused on /v1/* model calls with 403 key_scope_denied, and an inference-only key cannot touch deployments — least privilege is enforced on both directions, so a CI/CD key can never silently draw down inference spend
Revocable instantly — revoking a key makes it fail on the very next request (hash lookup miss; no grace period)
Rate limited per key — 180 requests/min on the paid tier (60 while on welcome credits); over-limit calls get 429 with a Retry-After header
Per-key daily spend cap (optional) — set a cap at creation; over-cap calls get 402 even when the account balance is fine. Good for agent workloads.

Hygiene

One key per environment (dev / staging / prod) — rotate independently
Never ship keys in client-side code; the /api/v1/* surface is server-to-server
Rotated or leaked? Delete and re-mint in seconds — old keys die immediately
Check a key's status and balance any time:

curl https://api.runaii.cloud/v1/key -H "Authorization: Bearer sk-runaii-..."

{
  "data": { "label": "prod", "usage": 0.42, "rate_limit": { "requests": 60, "interval": "1m" } },
  "balance_credits": 8.74,
  "reserved_credits": 0.000042
}

reserved_credits is the in-flight estimate for requests currently executing.