REST API reference

Each endpoint with parameters, request and response schemas and an example request.

API version 1.0.0

Authentication

Metered endpoints accept the workspace API key as a bearer token or in the X-API-Key header. Keys are issued at signup and managed in the dashboard. Endpoints marked "No authentication" need no key.

apiKey	`X-API-Key: <api key>`
bearer	`Authorization: Bearer <api key>`

Base URL and keybash

export OSR_URL="https://<your deployment>"   # the site you signed up on
export OSR_API_KEY="osr_..."

Conventions

Requests and responses are JSON. Errors are {"detail": "..."} with a conventional status code; 422 lists the offending fields.
Every routed call returns X-Request-Id; quote it in POST /api/v1/feedback. The chat endpoint adds X-OSR-Target and X-OSR-Confidence.
429 carries Retry-After; a 403 with X-Upgrade: true means the feature exists but is not in your plan.
The machine-readable document is served at /openapi.json and the interactive Swagger UI at /api on the API host.

Endpoint groups

Routing5 endpoints	Route a request to a target and return the decision with its trace; optionally build a plan or execute it. Report outcomes for the learners and read statistics and the audit trail. get/api/v1/audit post/api/v1/feedback post/api/v1/route get/api/v1/stats get/api/v1/targets
OpenAI-compatible2 endpoints	OpenAI-compatible chat completions and model listing. Point an OpenAI SDK at the platform base URL and use `model: "auto"`; the router chooses the model per request. post/v1/chat/completions get/v1/models
Public endpoints12 endpoints	No API key required: deployment information, the model catalogue with live statistics, rankings and self-serve signup. get/api/v1/catalogue post/api/v1/estimate get/api/v1/info get/api/v1/llms get/api/v1/llms/{vendor}/{model} get/api/v1/models get/api/v1/models/recommended get/api/v1/models/{model_id} get/api/v1/rankings post/api/v1/signup get/api/v1/stats/public get/api/v1/status
Account, keys and tenants32 endpoints	The calling workspace: profile, usage, savings, activity log, API keys and tenants. get/api/v1/activity get/api/v1/alerts get/api/v1/events get/api/v1/governance get/api/v1/keys post/api/v1/keys delete/api/v1/keys/{key_id} get/api/v1/learning get/api/v1/me get/api/v1/me/audit post/api/v1/me/delete get/api/v1/notifications get/api/v1/notifications/channels post/api/v1/notifications/channels patch/api/v1/notifications/channels/{channel_id} delete/api/v1/notifications/channels/{channel_id} post/api/v1/notifications/channels/{channel_id}/test get/api/v1/notifications/deliveries post/api/v1/notifications/read get/api/v1/notifications/unread get/api/v1/onboarding get/api/v1/policy put/api/v1/policy delete/api/v1/policy get/api/v1/savings get/api/v1/signals get/api/v1/telemetry/series get/api/v1/tenants put/api/v1/tenants delete/api/v1/tenants/{slug} get/api/v1/trace/{request_id} get/api/v1/usage
Workspaces14 endpoints	Organization workspaces: members, roles, invitations and organization SSO (browser sessions only). patch/api/v1/workspace delete/api/v1/workspace get/api/v1/workspace/audit post/api/v1/workspace/invites delete/api/v1/workspace/invites/{invite_id} get/api/v1/workspace/members patch/api/v1/workspace/members/{user_id} delete/api/v1/workspace/members/{user_id} get/api/v1/workspace/sso put/api/v1/workspace/sso delete/api/v1/workspace/sso get/api/v1/workspaces post/api/v1/workspaces post/api/v1/workspaces/{account_id}/switch
Sign-in and sessions23 endpoints	Sign-in with GitHub, Google or an organization identity provider; browser sessions; and CLI sign-in with device codes (`osr login`): the CLI requests a code, the person approves it in the browser, the CLI receives a workspace API key. post/api/v1/auth/device/approve post/api/v1/auth/device/code post/api/v1/auth/device/deny post/api/v1/auth/device/token get/api/v1/auth/device/{user_code} get/api/v1/auth/discover get/api/v1/auth/identities delete/api/v1/auth/identities/{provider} get/api/v1/auth/invites/{token} post/api/v1/auth/invites/{token}/accept post/api/v1/auth/logout post/api/v1/auth/password delete/api/v1/auth/password post/api/v1/auth/password/forgot post/api/v1/auth/password/login post/api/v1/auth/password/reset get/api/v1/auth/providers get/api/v1/auth/sessions delete/api/v1/auth/sessions/{session_id} post/api/v1/auth/verify post/api/v1/auth/verify/send post/api/v1/auth/{provider}/callback get/api/v1/auth/{provider}/start
Billing2 endpoints	Plan upgrades through Stripe Checkout and the webhook that confirms them. post/api/v1/billing/checkout post/api/v1/billing/webhook
MCP server2 endpoints	Model Context Protocol server for IDEs and agents (VS Code, Cursor, Claude, Windsurf): `POST /mcp` speaks JSON-RPC with tools to route, quote, recommend, explain and ask; `GET /mcp` describes it. Authenticate like the REST API. get/mcp post/mcp
Marketplace16 endpoints	Browse, publish, install and rate agents, skills, personas, prompts, templates and tools. Each listing has a validated manifest the router can load; `GET /registry/{slug}/manifest` is what `registry://` references resolve to. get/api/v1/me/installs get/api/v1/me/listings get/api/v1/registry post/api/v1/registry get/api/v1/registry/kinds get/api/v1/registry/{slug} patch/api/v1/registry/{slug} post/api/v1/registry/{slug}/archive post/api/v1/registry/{slug}/install get/api/v1/registry/{slug}/manifest get/api/v1/registry/{slug}/reviews put/api/v1/registry/{slug}/reviews delete/api/v1/registry/{slug}/reviews post/api/v1/registry/{slug}/submit post/api/v1/registry/{slug}/unarchive post/api/v1/registry/{slug}/versions
Model providers1 endpoint	Model providers: `GET /providers` is the public, OpenRouter-style view of what this deployment executes on (provider, upstream model, prices, health per executable target - never credentials); the `/admin/providers` endpoints add, check and map OpenAI-compatible endpoints at run time, and every API replica picks the change up without a restart. get/api/v1/providers