API Reference

All endpoints are prefixed with the base URL of your instance (e.g. https://api.runne.run). Authentication modes:

• Session — the runne_session cookie (customer dashboard). Ownership-checked routes additionally require that the session owns the workspace.
• API key — Authorization: Bearer rn_live_… or x-api-key: rn_live_….
• Webhook — HMAC signature in X-YooKassa-Signature.
• Public — no authentication.

Auth & session

Method	Path	Auth	Scope	Description
POST	/v1/auth/register	Public (auth rate limit 5/min/IP)	—	Register {email, password, name}; auto-login, 201 {customer_id, email}
POST	/v1/auth/login	Public (auth rate limit 10/min/IP)	—	Login {email, password}; 200 {expires_at} + session cookie
POST	/v1/auth/logout	Session	—	Revoke session jti server-side, clear cookie; {success: true}
GET	/v1/auth/me	Session	—	{customer_id, email, name, status, is_platform_admin}

Workspaces

Method	Path	Auth	Scope	Description
POST	/v1/workspaces	Session	—	Create workspace {name}; 201 workspace DTO
GET	/v1/workspaces	Session	—	List own workspaces; {workspaces: [...]}

API keys

Method	Path	Auth	Scope	Description
POST	/v1/workspaces/{workspace_id}/api-keys	Session (owner)	—	Create key {name, scopes[], rate_limit?}; 201 incl. raw_key (once)
GET	/v1/workspaces/{workspace_id}/api-keys	Session (owner)	—	List keys; {api_keys: [...]}
DELETE	/v1/workspaces/{workspace_id}/api-keys/{api_key_id}	Session (owner)	—	Revoke key; {success: true}

Payments & webhooks

Method	Path	Auth	Scope	Description
POST	/v1/payments	Session	—	Create YooKassa payment {workspace_id, amount_rubles, description?}; 201
GET	/v1/payments?workspace_id=	Session	—	List payments for own workspace
POST	/webhooks/yookassa	Webhook (HMAC-SHA256)	—	Process payment.succeeded/canceled, receipt.succeeded/canceled (idempotent)

Ledger & balance

Method	Path	Auth	Scope	Description
GET	/v1/workspaces/{workspace_id}/transactions	Session (owner)	—	Transaction history ?type=&from=&to=&limit=&offset=
GET	/v1/workspaces/{workspace_id}/balance	Session (owner)	—	{balance, updated_at}
GET	/v1/balance	API key	balance:read	{balance, currency, updated_at}

Usage & cost

Method	Path	Auth	Scope	Description
POST	/v1/cost/estimate	Public	—	Estimate cost {model, max_tokens}
GET	/v1/workspaces/{workspace_id}/usage-report	Session (owner)	—	Aggregated usage `?from=&to=&group_by=day

Quotas

Method	Path	Auth	Scope	Description
GET	/v1/workspaces/{workspace_id}/quota	Session (owner)	—	Current quota; `{quota:
GET	/v1/workspaces/{workspace_id}/quota/usage	Session (owner)	—	Current-period usage; {usage: {...}}

Chat completions

Method	Path	Auth	Scope	Description
POST	/v1/chat/completions	API key + rate limit	chat:write	OpenAI-compatible {model, messages[], max_tokens?}; mock provider in beta

Models

Method	Path	Auth	Scope	Description
GET	/v1/models	Public	—	List active models with current pricing
GET	/v1/models/{provider}/{model}	Public	—	Single model (no pricing in response)

Admin (platform admin only)

Requires a session whose customer is_platform_admin is true. Non-admins receive 403.

Method	Path	Description
GET	/v1/admin/dashboard/overview	System overview metrics
GET	/v1/admin/dashboard/top-workspaces	Top workspaces by usage (?limit=)
GET	/v1/admin/dashboard/top-models	Top models by usage (?limit=)
GET	/v1/admin/customers	List customers with pagination (?page=&limit=&status=)
GET	/v1/admin/customers/{customer_id}	Customer card: profile + workspaces
PUT	/v1/admin/customers/{customer_id}/status	Set status `{status: active
POST	/v1/admin/workspaces/{workspace_id}/adjust	Adjust balance {amount, description} (signed decimal)
PUT	/v1/admin/workspaces/{workspace_id}/quota	Update quota
PUT	/v1/admin/models/{provider}/{model}/pricing	Update model pricing
GET	/v1/admin/models/{provider}/{model}/pricing-history	Pricing history
GET	/v1/admin/workspaces/{workspace_id}/payments	Workspace payments
GET	/v1/admin/workspaces/{workspace_id}/receipts	Workspace receipts

System

Method	Path	Auth	Description
GET	/health	Public	{status: "ok"}
GET	/	Public	Service info

Error envelope

Not all non-2xx responses share one envelope. Domain errors use { "error": { "code": "…", "message": "…" } }; 400 validation errors use { "success": false, "error": { … } } (no code); some 401/403 responses (webhook signature, api-key ownership) return a flat { "error": "…" } string. See Errors for the code table and handling guidance.