{ "openapi": "3.1.0", "info": { "title": "Autonomous Relay Agents API", "version": "0.1.0", "summary": "One OpenAI-compatible endpoint in front of every model provider you already pay for.", "description": "Every model runs on **your own provider credential** (BYOK): add one with `POST /v1/byok` before anything will route. Nothing is resold, and nothing is added to the cost of a token.\n\n**Two classes of key**, told apart by prefix. `ar-v1-…` inference keys make model requests; `ar-mgmt-…` management keys administer the account. Each is refused on the other's routes. The dashboard's session cookie acts as the management key that created it -- and on `/v1/chat/completions`, as the organization's playground inference key.\n\n**Errors** share one envelope: `{\"error\": {\"code\", \"message\", \"metadata\": {\"error_type\", …}}}`. `code` is usually the HTTP status; where it is not, the operation says so. One response does not use the envelope: the jurisdiction refusal (451). An unknown route answers it with 404 `not_found`.\n\nThis document is checked against the code: a test fails when a route is registered that it does not describe. Field shapes are kept in step by hand.", "contact": { "name": "Tech Service 4U Inc.", "url": "https://autonomousrelay.com", "email": "support@autonomousrelay.com" }, "termsOfService": "https://autonomousrelay.com/terms" }, "servers": [ { "url": "https://autonomousrelay.com", "description": "Production" }, { "url": "https://api.autonomousrelay.com", "description": "Production -- the same API on the same certificate, on its own hostname" } ], "tags": [ { "name": "Inference", "description": "Model requests." }, { "name": "Catalog", "description": "Models, their endpoints and providers. Public." }, { "name": "Keys", "description": "API keys." }, { "name": "Usage", "description": "What was requested, and what it cost." }, { "name": "Credits", "description": "Balance and purchases." }, { "name": "Billing", "description": "The plans, per organisation, any number of members; inference is never marked up. A 14-day trial of Team, then **Pro** ($29/month): guardrails (create, assign), presets, classifiers, usage-alert channels (not the runaway setting, a safety control) and the CSV export; **Team** ($99): Pro plus invitations, workspace members, a second workspace, report branding and client reports; **Business** ($399): Team plus single sign-on and SCIM; **Enterprise**: an invoiced annual contract. Without a plan the core keeps working -- inference on your own provider keys, API keys, activity, logs, members, the first workspace. Creating or changing a feature the plan does not include answers **402 `subscription_required`**, naming the plan it needs. What was set up keeps running, stays readable and can be deleted." }, { "name": "BYOK", "description": "Your provider credentials. Required before anything routes." }, { "name": "Alerts", "description": "Usage alerts: where you are told a key is nearing its spend ceiling." }, { "name": "Files", "description": "Upload once, refer to by id. Off unless the deployment enables it, pending a privacy review." }, { "name": "Videos", "description": "Video generation jobs: submit, poll, download. Off unless the deployment enables it, pending a privacy review." }, { "name": "Batches", "description": "Chat requests run through the provider's own batch API, at its batch price, within 24 hours." }, { "name": "Classifiers", "description": "Organisation rules that tag each request from content-free signals, and may route a match through a preset." }, { "name": "Plugins", "description": "The plugin marketplace: MCP servers their developers host, reviewed for listing, installed per organisation and offered to the model with `{\"type\": \"autonomousrelay:plugin\", \"plugin\": \"\"}`." }, { "name": "Tools", "description": "Server tools: declared in tools[] as `{\"type\": \"autonomousrelay:\"}`, run by the gateway inside the request." }, { "name": "Presets", "description": "Named, versioned request settings, used as `\"model\": \"@preset/\"`." }, { "name": "Observability", "description": "Broadcast: a metadata record of each request, sent to your webhook, OpenTelemetry endpoint, S3-compatible bucket, Langfuse or Datadog." }, { "name": "Workspaces", "description": "One per client: separate keys, budgets and spend under one account." }, { "name": "Status", "description": "Measured service status." }, { "name": "Reports", "description": "White-label client reports: the agency's branding, and a client's month as numbers." }, { "name": "Audit", "description": "The organisation's audit log: who changed what, and when. Owner or Admin." }, { "name": "Members", "description": "Team seats. Roles: Owner (everything, including members), Developer (keys, provider keys, limits, workspaces, alerts, agents; reads billing), Finance (usage, exports, credits and checkout; changes nothing else). A management key with no person behind it has full power. Every management route shares one rate limit per key: 300 requests a minute, 20,000 a day (429 past it)." }, { "name": "Agents", "description": "Agents named in X-Autonomous-Relay-Agent: their spend, and budgets that bind across every key they use." }, { "name": "Guardrails", "description": "Policy: allowlists, budgets, privacy and content filters." }, { "name": "Auth", "description": "Dashboard sign-in." }, { "name": "SCIM", "description": "Directory sync (SCIM 2.0): your Okta or Microsoft Entra ID directory creates and deactivates people, and its groups decide which workspaces they see. Business plan or above. The /v1/scim/v2 routes take the SCIM token from Settings, not a management key. The step-by-step guide is at /docs/scim." }, { "name": "Federation", "description": "Workload identity federation: a workload exchanges the identity token its platform already gives it for a short-lived inference token, so no long-lived key is stored next to it. Policies are Owner or Admin, on every plan. The step-by-step guide is at /docs/federation." }, { "name": "SSO", "description": "Single sign-on through your own identity provider, over OpenID Connect or SAML 2.0 (Okta, Microsoft Entra ID, Google Workspace, ADFS, any OIDC issuer or SAML IdP). Business plan or above; Owner or Admin. The step-by-step guide is at /docs/sso." }, { "name": "Runs", "description": "Agent runs (§17.1): one goal, many turns, one budget enforced across all of them." }, { "name": "MCP", "description": "Model Context Protocol, for coding agents. Every tool adapts a route documented above." }, { "name": "Meta", "description": "Health, region, and this document." } ], "paths": { "/v1/chat/completions": { "post": { "operationId": "createChatCompletion", "tags": [ "Inference" ], "summary": "Create a chat completion", "description": "OpenAI-compatible. Routes to an endpoint your guardrails and preferences allow, dispatches on your own provider credential, and fails over to the next candidate before the first byte ships -- walking `models[]` to exhaustion.\n\n**Free models without a key.** A free model (`GET /v1/models?free=true`: every price zero) can be used before you add any provider key: where the platform holds a free-model key for its provider, an organisation with no key of its own for that model is served on it, at $0, with no hold. At most 50 such requests per organisation per UTC day (the operator may set another figure), across every free model and key; past that the attempt is not sent and the request is a 429 with `metadata.reason: free_model_daily_limit`. Your own key has no such limit, and once you add one for the provider it is used instead. The provider's own free-tier limits still apply, and its errors pass through. Every model with a price is served on your own key only.\n\nWith `stream: true` the response is server-sent events: one `data:` line per `ChatCompletionChunk`, SSE comments (lines starting with `:`) as keepalives, a final chunk carrying `usage`, then `data: [DONE]`.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Metadata", "in": "header", "required": false, "description": "`enabled` adds `agentrouter_metadata`: on the final chunk when streaming, and beside `error` on an error once routing has begun. `X-Metadata` is accepted too.", "schema": { "enum": [ "enabled" ] } }, { "name": "X-Session-Id", "in": "header", "required": false, "description": "A sticky-routing key, used when the body has no `session_id`. The legacy `X-AgentRouter-Metadata` is accepted too.", "schema": { "type": "string" } }, { "name": "X-Anthropic-Beta", "in": "header", "required": false, "description": "Forwarded to Anthropic as `anthropic-beta`.", "schema": { "type": "string" } }, { "name": "HTTP-Referer", "in": "header", "required": false, "description": "Your app's URL, for attribution. The app listing keeps its path; each request row keeps only the scheme and host.", "schema": { "type": "string" } }, { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for: 1 to 64 letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. Recorded on the request, and bound by that agent's budgets (`PUT /v1/agents/{agent}/budgets/{interval}`) across every key it uses. A malformed value is a 400 before anything is spent. The legacy name `X-AgentsRouter-Agent` is accepted too.", "schema": { "type": "string" } }, { "name": "X-Title", "in": "header", "required": false, "description": "Your app's name. `X-App-Title` and `X-OpenRouter-Title` are accepted too.", "schema": { "type": "string" } }, { "name": "X-App-Visibility", "in": "header", "required": false, "description": "`hidden` keeps the app out of public listings. Read on the app's first request only.", "schema": { "enum": [ "hidden", "public" ] } }, { "name": "X-App-Categories", "in": "header", "required": false, "description": "Up to two comma-separated categories.", "schema": { "type": "string" } }, { "name": "X-Cache", "in": "header", "required": false, "description": "`bypass` answers from the provider and stores nothing, on a key with the response cache on.", "schema": { "enum": [ "bypass" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "The completion: JSON, or an event stream when `stream` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-cache": { "description": "On a key with the response cache on: `HIT` (answered from the cache -- no provider call, `usage.cost` 0 and `usage.cached` true), `MISS` (answered by the provider and stored), or `BYPASS` (the request sent `X-Cache: bypass`). Absent when the request is not cacheable: streamed, with server tools or plugins, `n` above 1, a `run_id`, or any content part that is not text.", "schema": { "enum": [ "HIT", "MISS", "BYPASS" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } }, "text/event-stream": { "schema": { "type": "string", "description": "`data: ` lines, then `data: [DONE]`." } } } }, "400": { "description": "`messages is required`, or `model is required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the worst-case hold. Once a balance is negative every request is refused, free models included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted (`budget_exceeded`; the message names the level and the limit), a content filter blocked the prompt (`guardrail_blocked`; the message names the labels, never the matched text), or the key is a management key -- in which case the body reports `code: 401` and `invalid_credentials`.\n\nWith a `run_id`, also `run_budget_exceeded` (§17.1). That one type covers every way a run refuses a turn -- its cost ceiling, `max_turns`, `max_tool_calls`, a `model_policy` that excludes the model, and a run that is no longer open. §17.1 specifies it for \"the run's budget and caps\", and the **message** names which one bound; a `model_policy` or closed-run refusal therefore carries a type that reads narrower than it is.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No endpoint can serve the model under your constraints (`no_endpoints_available`). `metadata.unsatisfied_filters` names the filters that emptied the set. Also `not_found` when `run_id` names a run this organization does not have -- a different problem from a run that ran out, and fixed differently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, every candidate was rate limited upstream, or -- `metadata.reason: free_model_daily_limit` -- a free model served without a key of your own, past the organisation's daily allowance (50 by default). The message gives the reset; `Retry-After` and `X-RateLimit-*` are set. Add your own key for unlimited use." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate failed upstream (`provider_error`). `metadata.provider_code` and `metadata.provider_name` describe the last.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`service_unavailable`: moderation could not run, so the request was not sent (or, after the model ran, its answer is withheld and billed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "529": { "description": "Every candidate was overloaded upstream. The body reports `code: 502`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/messages": { "post": { "operationId": "createMessage", "tags": [ "Inference" ], "summary": "Create a message (Anthropic's Messages API)", "description": "Anthropic-compatible: the Anthropic SDKs work with their base URL set to this host. The request is translated to a chat completion and served by the same pipeline, so every gate, routing rule, preset, server tool and file applies, and **any** model answers it, not only Claude. The answer comes back as a `message`, or with `stream: true` as Anthropic's events (`message_start`, `content_block_*`, `message_delta`, `message_stop`, `ping`).\n\nThe key goes in `x-api-key` (as the Anthropic SDK sends it) or `Authorization: Bearer`. `anthropic-version` is accepted and ignored; `anthropic-beta` is forwarded to Anthropic. A Claude name such as `claude-opus-4-8` or `claude-opus-4-8-20260101` means `anthropic/claude-opus-4.8`; any other model is named by its catalogue id. `models` (or `fallbacks: [{\"model\": ...}]`, at most three), `provider`, `session_id` and `run_id` work as on chat completions.\n\nNot taken: Anthropic's own server tools (declare `autonomousrelay:*` tools instead -- `autonomousrelay:plugin`, `autonomousrelay:mcp` and `autonomousrelay:connected` included, as on chat completions), images inside a `tool_result`, a document by URL, and `cache_control` (ignored). Thinking blocks sent back are dropped; tool-use arguments stream as one `input_json_delta` per call, once the model has finished.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "description": "An inference key, as the Anthropic SDK sends it. Used when there is no `Authorization` header.", "schema": { "type": "string" } }, { "name": "anthropic-version", "in": "header", "required": false, "description": "Accepted and ignored.", "schema": { "type": "string" } }, { "name": "anthropic-beta", "in": "header", "required": false, "description": "Forwarded to Anthropic.", "schema": { "type": "string" } }, { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "A catalogue id, or a Claude name (`claude-opus-4-8`)." }, "max_tokens": { "type": "integer", "minimum": 1 }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "enum": [ "user", "assistant" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } }, "required": [ "role", "content" ] } }, "system": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] }, "stream": { "type": "boolean" }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": { "type": "object" } }, "required": [ "name", "input_schema" ] } }, "tool_choice": { "type": "object", "properties": { "type": { "enum": [ "auto", "any", "tool", "none" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } } }, "thinking": { "type": "object", "properties": { "type": { "enum": [ "enabled", "disabled" ] }, "budget_tokens": { "type": "integer" } } }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string" } } }, "fallbacks": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" } }, "required": [ "model" ] }, "maxItems": 3, "description": "Models tried in order after `model`." } }, "required": [ "model", "max_tokens", "messages" ] } } } }, "responses": { "200": { "description": "A message, or an event stream when `stream` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The request id; `GET /v1/generation?id=` reads it." }, "type": { "enum": [ "message" ] }, "role": { "enum": [ "assistant" ] }, "model": { "type": "string", "description": "The model that served." }, "content": { "type": "array", "items": { "type": "object", "description": "`text`, `thinking` or `tool_use` blocks." } }, "stop_reason": { "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "refusal" ] }, "stop_sequence": { "type": [ "string", "null" ] }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "US dollars." }, "is_byok": { "type": "boolean" } } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "Anthropic's `event:` / `data:` pairs." } } } }, "400": { "description": "In Anthropic's envelope (`{\"type\": \"error\", \"error\": {\"type\": \"invalid_request_error\", ...}}`), like every refusal here: a field that cannot be translated, named.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "401": { "description": "`authentication_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "402": { "description": "`billing_error`: not enough credit for the worst-case hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "403": { "description": "`permission_error`: a budget, a content filter, or a management key. `error.metadata.error_type` carries our own type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "404": { "description": "`not_found_error`: no such model, or no endpoint under your constraints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "429": { "description": "`rate_limit_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "`api_error`: every candidate failed upstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "529": { "description": "`overloaded_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } } } } }, "/v1/responses": { "post": { "operationId": "createResponse", "tags": [ "Inference" ], "summary": "Create a response (OpenAI's Responses API)", "description": "OpenAI-compatible Responses API. The request is translated to a chat completion and served by the same pipeline, so every gate, routing rule, preset, server tool and file applies, and any model answers it. The answer is a `response`; with `stream: true`, the Responses events (`response.created`, `response.output_item.*`, `response.output_text.delta`, `response.function_call_arguments.*`, `response.completed` or `response.incomplete`), each with a `sequence_number`.\n\n**Stateless.** Nothing is stored, so `store: true`, `previous_response_id`, `conversation` and `background` are refused with a 400 rather than ignored; send the whole conversation as `input`. `store: false` is accepted.\n\nInput items: messages (`input_text`, `input_image` by URL or `file_id`, `input_file` by `file_data` or `file_id`), `function_call` and `function_call_output`; `reasoning` items are dropped. Tools: `function`, and our `autonomousrelay:*` declarations -- server tools, `autonomousrelay:plugin`, `autonomousrelay:mcp` and `autonomousrelay:connected`, as on chat completions; OpenAI's built-in tools are refused. `text.format` (`json_schema`, `json_object`), `reasoning.effort`, `max_output_tokens`, `tool_choice` and `parallel_tool_calls` map to their chat equivalents; `models` and `provider` work as on chat completions. Function-call arguments stream as one delta per call, once the model has finished.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "A catalogue id." }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] }, "instructions": { "type": "string", "description": "Sent as a system message ahead of the input." }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "stream": { "type": "boolean" }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "user": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object" } }, "tool_choice": { "anyOf": [ { "enum": [ "auto", "none", "required" ] }, { "type": "object", "properties": { "type": { "enum": [ "function" ] }, "name": { "type": "string" } } } ] }, "parallel_tool_calls": { "type": "boolean" }, "text": { "type": "object", "properties": { "format": { "type": "object" } } }, "reasoning": { "type": "object", "properties": { "effort": { "type": "string" } } }, "store": { "type": "boolean", "description": "Only `false` (or absent): nothing is stored." }, "models": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "object", "description": "Routing preferences, as on chat completions." } }, "required": [ "input" ] } } } }, "responses": { "200": { "description": "A response, or an event stream when `stream` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The request id; `GET /v1/generation?id=` reads it." }, "object": { "enum": [ "response" ] }, "created_at": { "type": "integer" }, "status": { "enum": [ "completed", "incomplete" ] }, "incomplete_details": { "type": [ "object", "null" ] }, "model": { "type": "string", "description": "The model that served." }, "output": { "type": "array", "items": { "type": "object", "description": "`message`, `reasoning` or `function_call` items." } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "US dollars." }, "is_byok": { "type": "boolean" } } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "`event:` / `data:` pairs, each with a `sequence_number`." } } } }, "400": { "description": "A field that needs a stored response (`store: true`, `previous_response_id`, `conversation`, `background`), or one that cannot be translated, named.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the worst-case hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted, a content filter blocked the input, or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such model, or no endpoint under your constraints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, or every candidate was rate limited upstream." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate failed upstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/completions": { "post": { "operationId": "createCompletion", "tags": [ "Inference" ], "summary": "Create a text completion (legacy)", "description": "OpenAI's legacy text completion, for clients that still call it. The prompt is sent as one user message and served by the chat pipeline -- every gate, routing rule and preset applies -- and the answer's text comes back as `choices[0].text`; with `stream: true`, as `text_completion` chunks ending in `data: [DONE]`.\n\nOne prompt per request: a list of more than one is refused, since each would be its own routed and billed request. The catalogue's models are chat models, so what only a true completion model can honour is refused rather than dropped: `suffix`, `echo`, `best_of` and `n` above 1, `logprobs` (chat completions return them), and token-id prompts.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "A catalogue id." }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 1 } ] }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "stream": { "type": "boolean" }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "stop": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "seed": { "type": "integer" }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "user": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "object", "description": "Routing preferences, as on chat completions." } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "The completion, or `text_completion` chunks when `stream` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The request id; `GET /v1/generation?id=` reads it." }, "object": { "enum": [ "text_completion" ] }, "created": { "type": "integer" }, "model": { "type": "string", "description": "The model that served." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "index": { "type": "integer" }, "logprobs": { "type": "null" }, "finish_reason": { "type": [ "string", "null" ] } } } }, "usage": { "type": "object", "description": "As on chat completions." } } } }, "text/event-stream": { "schema": { "type": "string", "description": "`data: ` lines, then `data: [DONE]`." } } } }, "400": { "description": "More than one prompt, a token-id prompt, or `suffix`, `echo`, `best_of`, `n` above 1 or `logprobs`, named.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the worst-case hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted, a content filter blocked the prompt, or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such model, or no endpoint under your constraints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, or every candidate was rate limited upstream." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate failed upstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/embeddings": { "post": { "operationId": "createEmbeddings", "tags": [ "Inference" ], "summary": "Create embeddings", "description": "OpenAI-compatible. Routed like a chat completion -- `model`, an optional `models[]` fallback list and `provider` preferences -- through the same gates in the same order: auth, rate limit, every budget, the content filters (a redacted input is what is embedded), your guardrails and privacy policy, a hold, and failover before anything is returned. Billed on the provider's prompt-token count.\n\nOnly models whose catalogue modality outputs embeddings are candidates; naming a chat model is a 400 saying so. `input` is a string or up to 2,048 strings; token arrays are refused, since the router cannot know which tokeniser the endpoint it picks will read them with.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for; bound by that agent's budgets, as on chat completions.", "schema": { "type": "string" } }, { "name": "HTTP-Referer", "in": "header", "required": false, "description": "Your app's URL, for attribution.", "schema": { "type": "string" } }, { "name": "X-Title", "in": "header", "required": false, "description": "Your app's name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "An embedding model id from `/v1/models`." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Fallbacks, tried in order after `model`." }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 2048 } ] }, "encoding_format": { "enum": [ "float", "base64" ], "description": "`base64` returns each vector as little-endian float32s, base64-encoded." }, "dimensions": { "type": "integer", "minimum": 1, "maximum": 16384, "description": "For models that can shorten their output; others refuse it upstream." }, "provider": { "type": "object", "description": "Routing preferences, as on chat completions." } }, "required": [ "input" ] } } } }, "responses": { "200": { "description": "One vector per input, in input order.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The request id, as on chat completions; `GET /v1/generation?id=` reads it." }, "object": { "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "enum": [ "embedding" ] }, "index": { "type": "integer" }, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string", "description": "base64, with `encoding_format: \"base64\"`." } ] } } } }, "model": { "type": "string", "description": "The model that served." }, "provider": { "type": "string", "description": "The provider that served." }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "US dollars." }, "is_byok": { "type": "boolean" }, "cost_details": { "type": "object", "properties": { "upstream_inference_cost": { "type": [ "number", "null" ], "description": "What your own provider bills you, on a BYOK request; null otherwise." } } } } } } } } } }, "400": { "description": "A malformed `input`, `encoding_format`, `dimensions` or `provider`; `model is required`; or the model is not an embedding model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the worst-case hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted (`budget_exceeded`), a content filter blocked the input (`guardrail_blocked`), or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No model by that name, or no endpoint can serve it under your constraints (`no_endpoints_available`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, or every candidate was rate limited upstream." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate failed upstream (`provider_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "524": { "description": "Every candidate timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/audio/speech": { "post": { "operationId": "createSpeech", "tags": [ "Inference" ], "summary": "Text to speech", "description": "OpenAI's request; the answer is the audio itself, in `response_format` (mp3 by default). Routed like embeddings -- `model`, `models` and `provider` as on chat completions, the same budgets, content filters (a redacted `input` is what is spoken) and guardrails. Only text-to-speech models with a published price are candidates, and the request is billed per character of `input`, at that price. `voice` is passed as given: each model has its own voices (`af_bella` on Kokoro, `Ashley` on Inworld, a free-text description on the VoiceDesign models), and its default when omitted.\n\nThe body is audio, so the request id travels in the `x-autonomous-relay-generation-id` header; `GET /v1/generation?id=` reads its cost.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "A text-to-speech model id from `/v1/models`." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Fallbacks, tried in order after `model`." }, "input": { "type": "string", "maxLength": 10000 }, "voice": { "type": "string", "description": "The model's own voice name or, on a VoiceDesign model, a description." }, "response_format": { "enum": [ "mp3", "opus", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "provider": { "type": "object", "description": "Routing preferences, as on chat completions." } }, "required": [ "input" ] } } } }, "responses": { "200": { "description": "The audio.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-autonomous-relay-generation-id": { "description": "The request id.", "schema": { "type": "string" } } }, "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "A malformed `input`, `voice`, `response_format` or `speed`; `model is required`; or the model is not a text-to-speech model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the worst-case hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted, a content filter blocked the input, or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No model by that name, or no endpoint can serve it -- `published_price` when it has no price we can compute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, or every candidate was rate limited upstream." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate failed upstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/audio/transcriptions": { "post": { "operationId": "createTranscription", "tags": [ "Inference" ], "summary": "Speech to text", "description": "OpenAI's multipart request: `file` (flac, mp3, mp4, mpeg, mpga, m4a, ogg, opus, wav or webm, at most 25 MB) and `model`, with optional `language` (ISO-639-1), `prompt` and `temperature`. Routed like embeddings, through the same budgets and guardrails; the content filters read `prompt`. Only speech-to-text models with a published price are candidates, and the request is billed per second of audio, as the provider measured it.\n\n`response_format`: `json` (`{text, usage}`), `verbose_json` (adds `language`, `duration`, `segments`, `words`), or `text` (the transcript as plain text). `usage` is `{type: \"duration\", seconds, cost, ...}`. The request id is also in the `x-autonomous-relay-generation-id` header.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "model": { "type": "string", "description": "A speech-to-text model id from `/v1/models`." }, "language": { "type": "string" }, "prompt": { "type": "string" }, "temperature": { "type": "number" }, "response_format": { "enum": [ "json", "verbose_json", "text" ] } }, "required": [ "file", "model" ] } } } }, "responses": { "200": { "description": "The transcript.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-autonomous-relay-generation-id": { "description": "The request id.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "usage": { "type": "object", "properties": { "type": { "enum": [ "duration" ] }, "seconds": { "type": "number" }, "cost": { "type": "number", "description": "US dollars." }, "is_byok": { "type": "boolean" } } } } } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "No file, a file that is not audio, a malformed field, or the model is not a speech-to-text model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the worst-case hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted, a content filter blocked the prompt, or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No model by that name, or no endpoint can serve it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The file is over 25 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, or every candidate was rate limited upstream." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate failed upstream, or answered without the duration it is billed on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/images/generations": { "post": { "operationId": "createImage", "tags": [ "Inference" ], "summary": "Generate images", "description": "OpenAI's request and response, routed like embeddings: `model`, `models` and `provider` as on chat completions, through the same budgets, content filters (a redacted prompt is what is drawn) and guardrails. Only text-to-image models with a **published output price** are candidates; a model whose price cannot be computed from the request (per token, tiered by megapixel) is not served, and the 404 names `published_price`.\n\nBilled at that price, per image or per megapixel of `size` (`(width/1024) x (height/1024)`), for the images actually returned; `GET /v1/models/{author}/{slug}/endpoints` shows each endpoint's `image_output` price and its `image_output_unit`. Images come back as `b64_json` only: nothing is hosted, so there is no URL to give. Up to 4 images; each side of `size` from 256 to 2048 (models may accept less).", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "A text-to-image model id from `/v1/models`." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Fallbacks, tried in order after `model`." }, "prompt": { "type": "string" }, "n": { "type": "integer", "minimum": 1, "maximum": 4 }, "size": { "type": "string", "description": "`WIDTHxHEIGHT` or `auto` (1024x1024)." }, "response_format": { "enum": [ "b64_json" ] }, "provider": { "type": "object", "description": "Routing preferences, as on chat completions." } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "The images.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The request id; `GET /v1/generation?id=` reads it." }, "created": { "type": "integer" }, "model": { "type": "string", "description": "The model that served." }, "provider": { "type": "string", "description": "The provider that served." }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "revised_prompt": { "type": "string" } } } }, "usage": { "type": "object", "properties": { "images": { "type": "integer" }, "cost": { "type": "number", "description": "US dollars." }, "is_byok": { "type": "boolean" } } } } } } } }, "400": { "description": "A malformed `prompt`, `n`, `size` or `response_format`; `model is required`; or the model is not a text-to-image model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the worst-case hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted, a content filter blocked the prompt, or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No model by that name, or no endpoint can serve it -- `published_price` when it has no output price we can compute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, or every candidate was rate limited upstream." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate failed upstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "524": { "description": "Every candidate timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rerank": { "post": { "operationId": "createRerank", "tags": [ "Inference" ], "summary": "Rerank documents against a query", "description": "Each document's relevance to the query, most relevant first -- the request and response shape Cohere and Jina share. Routed and billed like embeddings: `model`, `models` and `provider` as on chat completions, the same budgets, content filters (a redacted query or document is what is scored) and guardrails, and the provider's input-token count as the bill. Only reranker models are candidates; another kind is a 400 that says so.\n\nServed today by DeepInfra's Qwen3 rerankers. Up to 1,000 documents, each a string or `{\"text\": ...}`. `instruction` steers the task on models that take one.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "A reranker model id from `/v1/models`." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Fallbacks, tried in order after `model`." }, "query": { "type": "string" }, "documents": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } ] }, "minItems": 1, "maxItems": 1000 }, "top_n": { "type": "integer", "minimum": 1, "description": "How many results to return; all by default." }, "return_documents": { "type": "boolean", "description": "Include each result's text." }, "instruction": { "type": "string", "description": "Steers the reranking task, on models that take one." }, "provider": { "type": "object", "description": "Routing preferences, as on chat completions." } }, "required": [ "query", "documents" ] } } } }, "responses": { "200": { "description": "The results, most relevant first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The request id; `GET /v1/generation?id=` reads it." }, "object": { "enum": [ "list" ] }, "model": { "type": "string", "description": "The model that served." }, "provider": { "type": "string", "description": "The provider that served." }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "relevance_score": { "type": "number" }, "document": { "type": "object", "properties": { "text": { "type": "string" } } } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "US dollars." }, "is_byok": { "type": "boolean" } } } } } } } }, "400": { "description": "A malformed `query`, `documents`, `top_n`, `return_documents` or `instruction`; `model is required`; or the model is not a reranker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the worst-case hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted, a content filter blocked the input, or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No model by that name, or no endpoint can serve it under your constraints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, or every candidate was rate limited upstream." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate failed upstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "524": { "description": "Every candidate timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/route/preview": { "post": { "operationId": "previewRoute", "tags": [ "Inference" ], "summary": "Preview how a request would route", "description": "Answers \"why would I get that model, from that provider?\" **before** the money is spent. Router metadata answers it afterwards; this runs the same gates, the same filters and the same ranking against a request that is never dispatched.\n\nIt mirrors `POST /v1/chat/completions` gate for gate and in order: the same auth, the same budget checks in the same precedence, the same content filter applied before routing, the same per-model candidate load, filter and rank, the same fallback depth, and the same sticky hoist.\n\nIt has **no side effects**. No ledger hold, no run reservation, no request row, no sticky pin written, no provider contacted. Rate limited in its own bucket, so debugging a routing problem never eats the quota needed to fix it.\n\nRead `ordering` before trusting `cascade` as a prediction: the default ranking is a weighted random draw, and `sampled` means a real request draws again.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Session-Id", "in": "header", "required": false, "description": "A sticky-routing key, used when the body has no `session_id`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePreviewRequest" } } } }, "responses": { "200": { "description": "How this request would route. A 200 with `would_dispatch: false` is the normal way to report \"this would be refused\" -- the preview succeeded, the request it describes would not.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoutePreview" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`model is required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "description": "Previews are counted in their own bucket, separately from inference." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/models": { "get": { "operationId": "listModels", "tags": [ "Catalog" ], "summary": "List models", "description": "Public. Rate limited per client address: 120 a minute, 20,000 a day.", "security": [], "x-auth": "public", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "required": false, "description": "A case-insensitive substring of the name or id.", "schema": { "type": "string" } }, { "name": "model_authors", "in": "query", "required": false, "description": "Comma-separated authors, e.g. `anthropic,openai`.", "schema": { "type": "string" } }, { "name": "context", "in": "query", "required": false, "description": "Minimum context length, in tokens.", "schema": { "type": "integer" } }, { "name": "output_modalities", "in": "query", "required": false, "description": "Comma-separated; the model produces ANY of them: `text`, `image`, `audio`, `video`, `embedding`, `rerank`. Other values are ignored.", "schema": { "type": "string" } }, { "name": "input_modalities", "in": "query", "required": false, "description": "Comma-separated; the model accepts ALL of them: `text`, `image`, `file`, `audio`, `video`. Other values are ignored.", "schema": { "type": "string" } }, { "name": "max_prompt_price", "in": "query", "required": false, "description": "The most the cheapest endpoint may charge for input, in USD per million tokens. `total_count` counts after it.", "schema": { "type": "number", "minimum": 0 } }, { "name": "free", "in": "query", "required": false, "description": "`true`: only models whose every price is zero (the catalogue's `is_free`).", "schema": { "enum": [ "true" ] } }, { "name": "sort", "in": "query", "required": false, "description": "Anything else sorts by id.", "schema": { "enum": [ "newest", "context-high-to-low", "pricing-low-to-high" ] } } ], "responses": { "200": { "description": "A page of models.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "total_count": { "type": "integer" }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ] } } } }, "required": [ "data", "total_count" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/models/{author}/{slug}": { "get": { "operationId": "getModel", "tags": [ "Catalog" ], "summary": "Get a model", "description": "Public and rate limited, as the list is. `pricing` is absent here; the endpoints route has every endpoint's prices.", "security": [], "x-auth": "public", "parameters": [ { "name": "author", "in": "path", "required": true, "description": "e.g. `anthropic`.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "e.g. `claude-sonnet-5`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Model" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/models/{author}/{slug}/endpoints": { "get": { "operationId": "listModelEndpoints", "tags": [ "Catalog" ], "summary": "List a model's endpoints", "description": "Public and rate limited. Every provider serving the model, with its price, measured uptime and latency, and tool-call reliability.", "security": [], "x-auth": "public", "parameters": [ { "name": "author", "in": "path", "required": true, "description": "e.g. `anthropic`.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "e.g. `claude-sonnet-5`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Model" }, { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/ModelEndpoint" } } }, "required": [ "endpoints" ] } ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/models/{author}/{slug}/availability": { "get": { "operationId": "getModelAvailability", "tags": [ "Catalog" ], "summary": "A model's availability per provider over the last week", "description": "Public and rate limited. For each provider that served the model in the last 7 UTC days, one figure per day: the share of dispatches it answered without failing on its side (a 5xx, unreachable, a broken stream). A caller's own errors -- a bad request, their key's rate limit -- do not count against it. A day with fewer than `min_dispatches` dispatches, or from fewer than `min_organizations` organisations, is `null`: not measured.", "security": [], "x-auth": "public", "parameters": [ { "name": "author", "in": "path", "required": true, "description": "e.g. `anthropic`.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "e.g. `claude-sonnet-5`.", "schema": { "type": "string" } } ], "responses": { "200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "YYYY-MM-DD, UTC." }, "available": { "type": [ "number", "null" ] } }, "required": [ "day", "available" ] } } }, "required": [ "provider", "days" ] } }, "days": { "type": "integer" }, "min_dispatches": { "type": "integer" }, "min_organizations": { "type": "integer" } }, "required": [ "data" ], "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/models/{author}/{slug}/price-history": { "get": { "operationId": "getModelPriceHistory", "tags": [ "Catalog" ], "summary": "How a model's input and output prices have changed, per provider", "description": "Public and rate limited. One series per provider and SKU (`prompt`, `completion`), oldest first: each point is a USD-per-token price and the time it took effect (`from`) and was replaced (`to`, null for the current price). Prices are effective-dated, so every change since the catalogue began recording them is here; an unchanged price written again is one point.", "security": [], "x-auth": "public", "parameters": [ { "name": "author", "in": "path", "required": true, "description": "e.g. `anthropic`.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "e.g. `claude-sonnet-5`.", "schema": { "type": "string" } } ], "responses": { "200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "provider_name": { "type": "string" }, "sku": { "type": "string", "description": "`prompt` or `completion`." }, "points": { "type": "array", "items": { "type": "object", "properties": { "usd": { "type": "string", "description": "USD per token." }, "from": { "type": "string", "description": "ISO 8601." }, "to": { "type": [ "string", "null" ] } }, "required": [ "usd", "from", "to" ] } } }, "required": [ "provider", "provider_name", "sku", "points" ] } } }, "required": [ "data" ], "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/home": { "get": { "operationId": "getHome", "tags": [ "Catalog" ], "summary": "Everything the home page shows", "description": "Public and rate limited, cached 30 seconds. The first 60 models, the providers, the purchase fee schedule, and the endpoints of the first six models -- each exactly as its own operation returns it. A part that could not be read is null; an endpoints read that failed is left out.", "security": [], "x-auth": "public", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "models": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "total_count": { "type": "integer" } }, "required": [ "data", "total_count" ] }, { "type": "null" } ] }, "providers": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "fee_bps": { "type": "integer" }, "fee_min": { "type": "number", "description": "US dollars." }, "min_purchase": { "type": "number", "description": "US dollars." }, "configured": { "type": "boolean" }, "purchasable": { "type": "boolean" } } }, { "type": "null" } ] }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/ModelEndpoint" } } }, "required": [ "model", "endpoints" ] } } }, "required": [ "models", "providers", "fees", "endpoints" ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/free-tier": { "get": { "operationId": "getFreeTier", "tags": [ "Catalog" ], "summary": "Whether free models work without a provider key here", "description": "Public and rate limited. Whether this deployment serves the catalogue's free models without a provider key of your own, on its own key: `available`, the daily request limit per organisation, and the models it applies to. `available` is false, and `models` empty, when it does not -- then every model, free ones included, runs on your own provider key.", "security": [], "x-auth": "public", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "daily_limit": { "type": "integer" }, "models": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/catalog/changes": { "get": { "operationId": "getCatalogChanges", "tags": [ "Catalog" ], "summary": "Models added and prices changed in the catalogue lately", "description": "Public and rate limited. Ready models added in the last `days` days (default 30, at most 90), newest first, and every input (`prompt`) or output (`completion`) per-token price that changed on an endpoint in that window -- rises and drops -- with the price before and after, in USD per token. A change is the importer replacing an endpoint's price: the same definition the `price_drop` alert uses.", "security": [], "x-auth": "public", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "name": { "type": "string" }, "at": { "type": "string", "description": "ISO 8601." } }, "required": [ "model", "name", "at" ] } }, "price_changes": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "sku": { "type": "string", "description": "`prompt` or `completion`." }, "from_usd": { "type": "string", "description": "USD per token." }, "to_usd": { "type": "string", "description": "USD per token." }, "at": { "type": "string", "description": "ISO 8601." } }, "required": [ "model", "name", "provider", "sku", "from_usd", "to_usd", "at" ] } } }, "required": [ "added", "price_changes" ] }, "days": { "type": "integer" } }, "required": [ "data", "days" ], "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/models/{author}/{slug}/price-alerts": { "post": { "operationId": "subscribeModelPriceAlerts", "tags": [ "Catalog" ], "summary": "Ask to be emailed when a model's price drops", "description": "Public; no account. Double opt-in: the address is sent one confirmation email, and nothing else until its link is clicked; an unconfirmed request is deleted after 7 days. Once confirmed, an email is sent when the model's input or output price drops on any provider -- once per drop, several models' drops in one email -- each with a one-click unsubscribe link. The answer is the same 202 whether or not an email was sent (an address already subscribed, over its limit of 20 models or of requests per day), so it says nothing about any address. Rate limited per client address and per email address.", "security": [], "x-auth": "public", "parameters": [ { "name": "author", "in": "path", "required": true, "description": "e.g. `anthropic`.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "e.g. `claude-sonnet-5`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The address to email." }, "lang": { "enum": [ "en", "fr" ], "description": "The language of the emails. Default `en`." } }, "required": [ "email" ] } } } }, "responses": { "202": { "description": "Check your inbox.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "enum": [ "check_inbox" ] }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`email` is not an email address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Email is not configured on this deployment (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/price-alerts/availability": { "get": { "operationId": "getPriceAlertAvailability", "tags": [ "Catalog" ], "summary": "Whether price-drop emails can be requested here", "description": "Public. `available` is false on a deployment with no email configured, where subscribing answers 503.", "security": [], "x-auth": "public", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/price-alerts/confirm": { "get": { "operationId": "confirmPriceAlerts", "tags": [ "Catalog" ], "summary": "Confirm a price-drop email subscription", "description": "The link in the confirmation email. Valid for 7 days, and idempotent while valid. Redirects to the model's page with `price_alert=confirmed`, or to `/models?price_alert=invalid` for an unknown or expired link.", "security": [ { "linkToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "From the confirmation email.", "schema": { "type": "string" } } ], "responses": { "303": { "description": "To the dashboard, with the outcome.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/price-alerts/unsubscribe": { "get": { "operationId": "unsubscribePriceAlerts", "tags": [ "Catalog" ], "summary": "Unsubscribe from price-drop emails (link)", "description": "The link in every price-alert email; no sign-in. Deletes the subscription -- or, for an email's \"stop all\" link, every subscription of the address -- and the address once it has none. Redirects to the model's page (or `/models`) with `price_alert=unsubscribed`, or `price_alert=invalid` for a link already used or unknown. Never refused by region: it only deletes.", "security": [ { "linkToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "From the email.", "schema": { "type": "string" } } ], "responses": { "303": { "description": "To the dashboard, with the outcome.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "unsubscribePriceAlertsOneClick", "tags": [ "Catalog" ], "summary": "Unsubscribe from price-drop emails (one-click, RFC 8058)", "description": "What a mail client POSTs to the `List-Unsubscribe` URL, with the body `List-Unsubscribe=One-Click` (form-encoded; ignored). The same deletion as the link.", "security": [ { "linkToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "From the email's List-Unsubscribe header.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "unsubscribed": { "type": "boolean" } }, "required": [ "unsubscribed" ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/providers": { "get": { "operationId": "listProviders", "tags": [ "Catalog" ], "summary": "List providers", "description": "Public and rate limited.", "security": [], "x-auth": "public", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/rankings/models": { "get": { "operationId": "getModelRankings", "tags": [ "Catalog" ], "summary": "Model rankings by tokens processed", "description": "Public and rate limited. Tokens processed per model -- prompt, completion, reasoning and cache, by the model that served them -- over `day` (since 00:00 UTC), `week` (7 days), `month` (30 days), or `trending` (the largest increase, this week against the week before). **A measure of use, not of quality.** Aggregated only, and a model is listed only once at least `min_organizations` (3) distinct organisations used it in the period; in `trending`, last week's figure is null when last week was below that threshold too. Recomputed at most every ten minutes.", "security": [], "x-auth": "public", "parameters": [ { "name": "range", "in": "query", "required": false, "description": "`day`, `week` (default), `month` or `trending`.", "schema": { "enum": [ "day", "week", "month", "trending" ] } } ], "responses": { "200": { "description": "The ranking.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "basis": { "type": "string" }, "not_a_quality_ranking": { "const": true }, "min_organizations": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "model": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "tokens": { "type": "integer" }, "share": { "type": "number", "minimum": 0, "maximum": 1 }, "available": { "type": "boolean", "description": "Whether the model is still in the catalogue. A retired model keeps its rank, since usage is history, but has no page to link to." }, "prior_tokens": { "type": [ "integer", "null" ], "description": "Trending only." }, "change_tokens": { "type": [ "integer", "null" ], "description": "Trending only." } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "An unknown `range`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited", "description": "The public per-address limit." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/rankings/apps": { "get": { "operationId": "getAppRankings", "tags": [ "Catalog" ], "summary": "The apps directory: apps by tokens processed", "description": "Public and rate limited. Apps are what requests name in `HTTP-Referer`; each is listed by its **domain only** (paths merged, `www.` dropped) -- never the `X-Title` or categories a caller sends, which anyone can set. A domain is listed once it has at least `min_requests` (100) completed requests in the period; apps whose first request sent `X-App-Visibility: hidden` never are, nor are local or private hosts. `week` (7 days, the default) or `month` (30). Recomputed at most every ten minutes.", "security": [], "x-auth": "public", "parameters": [ { "name": "range", "in": "query", "required": false, "description": "`week` (default) or `month`.", "schema": { "enum": [ "week", "month" ] } } ], "responses": { "200": { "description": "The directory.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "basis": { "type": "string" }, "min_requests": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "domain": { "type": "string" }, "tokens": { "type": "integer" }, "top_models": { "type": "array", "items": { "type": "string" }, "maxItems": 3 }, "retired_models": { "type": "array", "items": { "type": "string", "description": "Of top_models, those no longer in the catalogue." }, "maxItems": 3 } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "An unknown `range`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited", "description": "The public per-address limit." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/providers/{slug}": { "get": { "operationId": "getProvider", "tags": [ "Catalog" ], "summary": "Get a provider and the models it serves", "description": "Public and rate limited. The directory row, and every ready model the provider has an active endpoint for, with the endpoint's prompt and completion price, context, quantization, region and published uptime -- the same figures as the model's own endpoints list.", "security": [], "x-auth": "public", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "e.g. `anthropic`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Provider" }, { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "type": "object", "properties": { "model_id": { "type": "string" }, "model_name": { "type": "string" }, "quantization": { "type": [ "string", "null" ] }, "context_length": { "type": [ "integer", "null" ] }, "deployment_region": { "type": [ "string", "null" ] }, "pricing": { "type": "object", "description": "`prompt` and `completion`, USD per token, as strings.", "additionalProperties": { "type": "string", "description": "US dollars as a decimal string, so no precision is lost in JSON." } }, "uptime": { "description": "As on the model's endpoints list: null until the sample floor is met." } }, "required": [ "model_id", "model_name", "pricing" ] } } }, "required": [ "endpoints" ] } ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/key": { "get": { "operationId": "getCurrentKey", "tags": [ "Keys" ], "summary": "Inspect the calling key", "description": "For an inference key: its limit, what remains of it, and what it has spent plus what its in-flight requests have reserved.", "security": [ { "inferenceKey": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KeyInfo" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/keys": { "get": { "operationId": "listKeys", "tags": [ "Keys" ], "summary": "List keys", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "include_disabled", "in": "query", "required": false, "description": "Include revoked keys.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createKey", "tags": [ "Keys" ], "summary": "Create a key", "description": "The plaintext key is in this response and **never again**: only a salted hash is stored.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "limit": { "type": "number", "description": "A spend limit in USD. Omit for none." }, "limit_reset": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", "lifetime", null ], "description": "The window the ceiling covers, in UTC calendar terms. Null means lifetime: the ceiling never resets." }, "limit_mode": { "enum": [ "hard", "soft" ], "description": "`hard` (the default) refuses a request once the key is at or past its ceiling, with 403 `budget_exceeded`. `soft` serves it and adds an `x-autonomous-relay-limit-warning` header carrying the same sentence.", "default": "hard" }, "include_byok_in_limit": { "type": "boolean", "default": true, "description": "Count spend on your own provider credential toward the ceiling, at list price. On by default: every model is BYOK-only, so without it the ceiling would count nothing." }, "workspace_id": { "type": "string", "description": "Put the key in this workspace (client). Omit for the caller's own workspace. Another organisation's id is a 404." }, "class": { "enum": [ "inference", "management" ], "default": "inference" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the key stops authenticating (401 `key_expired`). With a time zone, in the future, within ten years. Omit for a key that does not expire." }, "rpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000, "description": "The key's own requests per minute, counted in calendar minutes on top of the account quota; null for none. Inference keys only." }, "tpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000000, "description": "The key's own tokens (prompt + completion) per minute; null for none. Requests are refused once the minute's count reaches it, and a request's tokens are counted when it finishes, so requests in flight can overshoot it. Inference keys only." }, "cache_enabled": { "type": "boolean", "default": false, "description": "Answer this key's repeated non-streaming chat completions from the response cache, at no cost. Inference keys only. An identical request gets the same answer, whatever its temperature." }, "cache_ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 3600, "description": "How long an answer stays cached." } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "string", "description": "The key. Store it now." }, "hash": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "class": { "enum": [ "inference", "management" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "rpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000, "description": "The key's own requests per minute, counted in calendar minutes on top of the account quota; null for none. Inference keys only." }, "tpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000000, "description": "The key's own tokens (prompt + completion) per minute; null for none. Requests are refused once the minute's count reaches it, and a request's tokens are counted when it finishes, so requests in flight can overshoot it. Inference keys only." }, "cache_enabled": { "type": "boolean" }, "cache_ttl_seconds": { "type": "integer" } }, "required": [ "key", "hash", "class" ] } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range or of the wrong type, named in the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The workspace named in `workspace_id` is not in this organisation." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/keys/{hash}": { "delete": { "operationId": "revokeKey", "tags": [ "Keys" ], "summary": "Revoke a key", "description": "Disables the key and ends every dashboard session it created.\n\n**Propagation is bounded at 10 seconds** (§17.4: \"publish that TTL\"). The instance serving this call stops accepting the key immediately; any other instance stops within the auth cache's TTL. That cache serves **no stale window** — past ten seconds the entry is refused and the caller waits on the database — so ten seconds is the real bound, not the point at which a refresh merely begins.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "The key's `hash`, from the list.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "updateKeyLimit", "tags": [ "Keys" ], "summary": "Change a key's spend limit, rates or expiry, or pause and resume it", "description": "Changes the ceiling, its window, its mode, whether BYOK spend counts, the key's requests and tokens per minute, the workspace, a pause or the expiry. Only these: a key's class, name and secret are fixed at creation. At least one field is required. The new ceiling applies at once on the instance serving this call and within the auth cache's 10-second TTL everywhere else.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "The key's `hash`, from the list.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": [ "number", "null" ], "description": "The new ceiling in USD; null removes it." }, "limit_reset": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", "lifetime", null ], "description": "The window the ceiling covers, in UTC calendar terms. Null means lifetime: the ceiling never resets." }, "limit_mode": { "enum": [ "hard", "soft" ], "description": "`hard` (the default) refuses a request once the key is at or past its ceiling, with 403 `budget_exceeded`. `soft` serves it and adds an `x-autonomous-relay-limit-warning` header carrying the same sentence." }, "include_byok_in_limit": { "type": "boolean" }, "workspace_id": { "type": "string", "description": "Move the key to this workspace of the same organisation." }, "paused": { "type": "boolean", "description": "false resumes a key paused by a runaway flag or by hand; true pauses it by hand. A paused key answers 403 `key_paused`." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set or move the expiry (with a time zone, in the future, within ten years); null removes it. Refused on the calling key and on a dashboard sign-in key, which would lock their holder out." }, "rpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000, "description": "The key's own requests per minute, counted in calendar minutes on top of the account quota; null for none. Inference keys only." }, "tpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000000, "description": "The key's own tokens (prompt + completion) per minute; null for none. Requests are refused once the minute's count reaches it, and a request's tokens are counted when it finishes, so requests in flight can overshoot it. Inference keys only." }, "cache_enabled": { "type": "boolean", "description": "Turn the response cache on or off for this key. Inference keys only. Turning it off stops lookups at once; entries already stored expire on their TTL, or go now with `DELETE /v1/cache`." }, "cache_ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "How long answers stored from now on stay cached." } } } } } }, "responses": { "200": { "description": "The key's ceiling as it now stands.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "hash": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "class": { "enum": [ "inference", "management" ] }, "limit": { "type": [ "number", "null" ], "description": "USD." }, "limit_reset": { "type": [ "string", "null" ] }, "limit_mode": { "enum": [ "hard", "soft" ] }, "include_byok_in_limit": { "type": "boolean" }, "paused": { "type": "boolean" }, "paused_reason": { "enum": [ "runaway", "manual", null ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "rpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000, "description": "The key's own requests per minute, counted in calendar minutes on top of the account quota; null for none. Inference keys only." }, "tpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000000, "description": "The key's own tokens (prompt + completion) per minute; null for none. Requests are refused once the minute's count reaches it, and a request's tokens are counted when it finishes, so requests in flight can overshoot it. Inference keys only." }, "cache_enabled": { "type": "boolean" }, "cache_ttl_seconds": { "type": "integer" } }, "required": [ "hash" ] } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range or of the wrong type, named in the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/activity": { "get": { "operationId": "listActivity", "tags": [ "Usage" ], "summary": "List recent requests", "description": "Newest first, keyset-paginated. Cost is summed per row, over the window.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "days", "in": "query", "required": false, "description": "The window, ending now.", "schema": { "type": "integer", "minimum": 1, "maximum": 31, "default": 7 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Opaque; do not parse it.", "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "description": "The model that served.", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": false, "description": "A provider slug.", "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "required": false, "description": "One client: a workspace id. A malformed id is a 400.", "schema": { "type": "string" } }, { "name": "agent", "in": "query", "required": false, "description": "One agent: the X-Autonomous-Relay-Agent value.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Requests a classifier tagged with this.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "The request status, e.g. `complete`.", "schema": { "type": "string" } }, { "name": "byok", "in": "query", "required": false, "description": "BYOK requests only, or none.", "schema": { "type": "boolean" } }, { "name": "app", "in": "query", "required": false, "description": "An `app_id`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" } }, "next_cursor": { "type": [ "string", "null" ] }, "window": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "days": { "type": "integer" } } } }, "required": [ "data", "next_cursor", "window" ] } } } }, "400": { "description": "`cursor is malformed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/activity/export.csv": { "get": { "operationId": "exportActivityCsv", "tags": [ "Usage" ], "summary": "Export a month of requests as CSV", "description": "One row per request in a UTC calendar month, for the account or one client (`workspace`). Columns: created_at, request_id, client, key, requested_model, served_model, provider, status, error_code, byok, prompt_tokens, completion_tokens, billed_usd (what this account was charged), list_price_usd (the tokens at catalogue list price: under BYOK, the number a client is re-billed on and the one budgets measure) and agent. Text cells that a spreadsheet would run as a formula are prefixed with a single quote. Capped at 200,000 rows, after which a `# truncated` line ends the file. At most 6 exports a minute per key.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "month", "in": "query", "required": false, "description": "YYYY-MM, UTC. Default: the current month.", "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "required": false, "description": "One client: a workspace id. Another organisation's is a 404.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The CSV, as an attachment.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "`month must be YYYY-MM` or `workspace must be a workspace id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "More than 6 exports a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/analytics/query": { "post": { "operationId": "queryAnalytics", "tags": [ "Usage" ], "summary": "Query usage analytics", "description": "Aggregates over your requests and what they cost -- the rows Activity and Logs read, so the numbers agree. Name at least one metric, up to two dimensions to group by, up to twenty filters on dimensions, a time range (default the last 7 days, at most 92) and a granularity for a series. `group_limit` keeps the top groups by the first metric over the whole range, so a series has the same groups in every bucket. `GET /v1/analytics/meta` lists every metric and dimension. A seat limited to some workspaces queries those alone.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metrics": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "string" }, "description": "e.g. `requests`, `spend_usd`, `total_tokens`, `error_rate`, `avg_ttft_ms`." }, "dimensions": { "type": "array", "maxItems": 2, "items": { "type": "string" }, "description": "e.g. `model`, `provider`, `api_key`, `workspace`, `agent`." }, "filters": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "field": { "type": "string", "description": "A dimension." }, "operator": { "enum": [ "eq", "neq", "in", "not_in" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 } ], "description": "A string for eq and neq, a list for in and not_in." } }, "required": [ "field", "operator", "value" ] } }, "time_range": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "granularity": { "enum": [ "none", "hour", "day", "week", "month" ], "default": "none" }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1000 }, "group_limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "order_by": { "type": "object", "properties": { "field": { "type": "string", "description": "A requested metric or dimension, or `time`." }, "direction": { "enum": [ "asc", "desc" ], "default": "desc" } }, "required": [ "field" ] } }, "required": [ "metrics" ] } } } }, "responses": { "200": { "description": "The aggregates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One row per group (and time bucket): `time` when there is a granularity, each dimension (null for a request without one), each metric as a number.", "additionalProperties": true } }, "metadata": { "type": "object", "properties": { "query_time_ms": { "type": "integer" }, "row_count": { "type": "integer" }, "truncated": { "type": "boolean", "description": "More rows matched than `limit`." }, "time_range": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "granularity": { "type": "string" } }, "required": [ "query_time_ms", "row_count", "truncated" ] } }, "required": [ "data", "metadata" ] } } } }, "400": { "description": "An unknown metric or dimension, too many of anything, a malformed filter or time range, or an order_by field that was not requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/analytics/meta": { "get": { "operationId": "getAnalyticsMeta", "tags": [ "Usage" ], "summary": "List analytics metrics and dimensions", "description": "Every metric, dimension, filter operator and granularity `POST /v1/analytics/query` accepts, and its limits.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "What can be queried.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "operators": { "type": "array", "items": { "type": "string" } }, "granularities": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": { "type": "integer" } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/analytics/metrics": { "get": { "operationId": "getAnalyticsMetrics", "tags": [ "Usage" ], "summary": "List analytics metrics and dimensions (alias)", "description": "The same as `GET /v1/analytics/meta`, under the name the design requirements use.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "What can be queried.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "operators": { "type": "array", "items": { "type": "string" } }, "granularities": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": { "type": "integer" } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/metrics": { "get": { "operationId": "getPrometheusMetrics", "tags": [ "Usage" ], "summary": "Scrape usage as Prometheus metrics", "description": "The caller's organisation in the Prometheus text exposition format (version 0.0.4), for a Prometheus `scrape_config` with the management key as `bearer_token`. Counters count finished requests since the start of the current UTC month and reset to zero at each month boundary, which `rate()` and `increase()` treat as an ordinary counter reset; `autonomousrelay_counters_since_timestamp_seconds` says when. Families: `autonomousrelay_requests_total{model,provider,status}`, `autonomousrelay_tokens_total{model,provider,type}` (type is `prompt` or `completion`), `autonomousrelay_spend_usd_total{model,provider}` (USD billed), the `autonomousrelay_request_duration_seconds{model,provider}` histogram, and the `autonomousrelay_active_keys{class}` gauge. The 25 models with the most requests keep their own `model` label; the rest are summed as `other`. A seat limited to some workspaces sees those alone. Computed at most every 15 seconds per organisation; a faster scrape reads the same numbers.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The metrics.", "content": { "text/plain; version=0.0.4; charset=utf-8": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/activity/summary": { "get": { "operationId": "getActivitySummary", "tags": [ "Usage" ], "summary": "Get activity totals", "description": "The KPI cards (§14.9), with the prior period of equal length beside them and a daily series for the sparklines. Both periods are read in one pass, so they cannot disagree about where \"now\" was.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "The window, ending now. The prior period is the same length again.", "schema": { "type": "integer", "minimum": 1, "maximum": 31, "default": 7 } }, { "name": "workspace", "in": "query", "required": false, "description": "One client: a workspace id. A malformed id is a 400.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Totals for the window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ActivityTotals" }, "previous": { "$ref": "#/components/schemas/ActivityTotals", "description": "The period of equal length immediately before this one." }, "series": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date-time" }, "requests": { "type": "integer" }, "spend": { "type": "number", "description": "US dollars." }, "tokens": { "type": "integer" } } } }, "window": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "days": { "type": "integer" } } } }, "required": [ "data", "previous", "series", "window" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/activity/{id}": { "get": { "operationId": "getActivityItem", "tags": [ "Usage" ], "summary": "Get one request", "description": "Everything recorded about one request (§14.10): the list row, plus the key that made it, its session and run, the usage lines it was billed on, and every dispatch to a provider in order. Metadata only -- stored content is `GET /v1/generation/{id}/content`. Another organisation's id is a 404.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The request id (`gen-…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ActivityDetail" } }, "required": [ "data" ] } } } }, "400": { "description": "`id must be a request id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/activity/upstream": { "get": { "operationId": "listUpstreamRequests", "tags": [ "Usage" ], "summary": "List upstream provider requests", "description": "One row per dispatch to a provider, newest first and keyset-paginated. A request that failed over twice appears three times -- filter by `request` to see a single generation's attempts in order.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "days", "in": "query", "required": false, "description": "The window, ending now.", "schema": { "type": "integer", "minimum": 1, "maximum": 31, "default": 7 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Opaque; do not parse it.", "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "required": false, "description": "One client: a workspace id. The dispatches made for its requests. A malformed id is a 400.", "schema": { "type": "string" } }, { "name": "request", "in": "query", "required": false, "description": "A generation id: every dispatch made for it.", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": false, "description": "A provider slug.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Whether the dispatch committed.", "schema": { "enum": [ "ok", "error" ] } } ], "responses": { "200": { "description": "A page of dispatches.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UpstreamRequest" } }, "next_cursor": { "type": [ "string", "null" ] }, "window": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "days": { "type": "integer" } } } }, "required": [ "data", "next_cursor", "window" ] } } } }, "400": { "description": "`cursor is malformed` or `workspace must be a workspace id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/activity/sessions": { "get": { "operationId": "listSessions", "tags": [ "Usage" ], "summary": "List conversations", "description": "Generations grouped by `session_id`, most recently active first. Only requests that carried one are included.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "days", "in": "query", "required": false, "description": "The window, ending now.", "schema": { "type": "integer", "minimum": 1, "maximum": 31, "default": 7 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Opaque; do not parse it.", "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "required": false, "description": "One client: a workspace id. A malformed id is a 400.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" } }, "next_cursor": { "type": [ "string", "null" ] }, "window": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "days": { "type": "integer" } } } }, "required": [ "data", "next_cursor", "window" ] } } } }, "400": { "description": "`cursor is malformed` or `workspace must be a workspace id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/generation": { "get": { "operationId": "getGeneration", "tags": [ "Usage" ], "summary": "Get one request's record", "description": "Which endpoint served it, at which price version, and what each SKU cost -- enough to recompute the charge.\n\n**Not the content.** Prompts and completions are stored only when your organisation has enabled input/output logging (§13.1), which is off by default and never retroactive; when it is on, the content is read from `GET /v1/generation/{id}/content`, not from here.", "security": [ { "inferenceKey": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "The `id` of a chat completion.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Generation" } }, "required": [ "data" ] } } } }, "400": { "description": "`id is required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/generation/{id}/content": { "get": { "operationId": "getGenerationContent", "tags": [ "Usage" ], "summary": "Get one generation's stored prompt and completion", "description": "§13.1. Returns content **only** if your organisation had input/output logging enabled when the generation was made.\n\nStored encrypted (AES-256-GCM, data key wrapped by Cloud KMS) in a table separate from request metadata, under an AAD bound to your organisation — a credential ciphertext cannot be read here and content cannot be read from the credential path. Deleted automatically past your configured retention.\n\nThis is the **only** read path for stored content, and it is yours. §13.1 forbids using it for training or analytics, and there is no internal reader.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The generation id (`gen-…`).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "request_id": { "type": "string" }, "content": { "type": "object", "additionalProperties": true, "description": "The request messages, the completion, and any tool calls." } }, "required": [ "request_id", "content" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "No stored content — the usual case, since logging is off by default and never retroactive." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/generation/feedback": { "post": { "operationId": "submitGenerationFeedback", "tags": [ "Usage" ], "summary": "Score a generation", "description": "Attach a score to a request your organisation made, so you can see which models your users rate well. `value` is a number from -1 to 1 -- thumbs down `-1`, thumbs up `1`, a finer rating mapped into the range. `label` is an optional slug (`helpful`, `wrong_answer`).\n\nOne score per generation per key: posting again from the same key replaces it. Any inference key of the organisation that made the request may score it, as any may read it with `GET /v1/generation`; another organisation's id is a 404.\n\n**No free text.** A `comment` is refused with a 400: a comment is content an end user typed, and the gateway stores no content.", "security": [ { "inferenceKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The generation id (`gen-…`)." }, "value": { "type": "number", "minimum": -1, "maximum": 1 }, "label": { "type": [ "string", "null" ], "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" } }, "required": [ "id", "value" ] } } } }, "responses": { "200": { "description": "The score as stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GenerationFeedback" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "A value outside -1..1, a label that is not a slug, a `comment`, or an unknown field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getGenerationFeedback", "tags": [ "Usage" ], "summary": "Read a generation's scores", "description": "Every score your organisation's keys attached to the generation, oldest first; an empty list when there are none. Another organisation's id is a 404.", "security": [ { "inferenceKey": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "The generation id (`gen-…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GenerationFeedback" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`id is required` or `id must be a generation id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/feedback/summary": { "get": { "operationId": "getFeedbackSummary", "tags": [ "Usage" ], "summary": "Feedback by model", "description": "The average score and the number of scores, by the model that served the request, over requests made in the last `days` days (default 30, at most 90). Most-scored first, at most 100 models. A workspace-limited person sees their workspaces' requests only.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "The window, ending now, by when the request was made.", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Scores by model.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "count": { "type": "integer" }, "average": { "type": "number", "minimum": -1, "maximum": 1 }, "positive": { "type": "integer", "description": "Scores above 0." }, "negative": { "type": "integer", "description": "Scores below 0." } }, "required": [ "model", "count", "average", "positive", "negative" ] } }, "days": { "type": "integer" } }, "required": [ "data", "days" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/files": { "get": { "operationId": "listFiles", "tags": [ "Files" ], "summary": "List files", "description": "Unexpired files, newest first, as `{\"object\": \"list\", \"data\": [...]}`. Off unless the deployment sets `FILES_ENABLED=true`: uploaded files are customer content at rest, which waits on a privacy review; until then every files route is a 403 saying so.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileObject" } } } } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "uploadFile", "tags": [ "Files" ], "summary": "Upload a file", "description": "OpenAI's shape: multipart/form-data with `file`, `purpose` (`user_data`, `assistants` or `vision`) and optionally `expires_after[seconds]` (3,600 to 2,592,000; default 30 days). A PDF, a PNG, JPEG, GIF or WebP image, or UTF-8 text, at most 10 MB, typed by its bytes; 500 MB per organisation. Stored encrypted. Use it in a completion as `{\"type\": \"file\", \"file\": {\"file_id\": \"file-…\"}}`. Inference key, or a person with config:write. Off unless the deployment sets `FILES_ENABLED=true`: uploaded files are customer content at rest, which waits on a privacy review; until then every files route is a 403 saying so.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "enum": [ "user_data", "assistants", "vision" ] }, "expires_after[seconds]": { "type": "integer" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "The stored file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" } } } }, "400": { "description": "Not a supported type, an unknown purpose, or an out-of-range expiry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "413": { "description": "Over 10 MB, or over the organisation's 500 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/files/{id}": { "get": { "operationId": "getFile", "tags": [ "Files" ], "summary": "Get a file's details", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file id (`file-…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteFile", "tags": [ "Files" ], "summary": "Delete a file", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "enum": [ "file" ] }, "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/files/{id}/content": { "get": { "operationId": "getFileContent", "tags": [ "Files" ], "summary": "Download a file", "description": "The bytes, as an attachment, to the organisation that uploaded them.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/evals": { "post": { "operationId": "runEval", "tags": [ "Inference" ], "summary": "Run an evaluation", "description": "A dataset, a task and up to 8 models (at most 400 cells), producing a scored comparison with per-cell cost and latency (§17.6). **Every cell is a real** `POST /v1/chat/completions` on your credentials -- the same rate limit, budgets, guardrails, routing and billing as if you had sent it, and a request row of its own -- so an evaluation is the same account, keys and routing you would run in production. A cell your rate limit refuses waits for the window and is tried again.\n\nThe answer streams as NDJSON: one `{\"type\": \"cell\", ...}` line per cell as it completes (four at a time), then `{\"type\": \"summary\", ...}` per model. **Nothing is stored**: the dataset arrives with the request, the outputs go back in the stream, and there is no run to fetch later.\n\nScorers: `none`, `exact` and `contains` (against each item's `expected`; case and spacing ignored unless `case_sensitive`), and `json` (the answer parses as JSON, code fences allowed). There is no regex scorer: a caller's pattern run over a model's answer can stall a backtracking engine, so pattern scoring waits for a linear-time one.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 8 }, "dataset": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "expected": { "type": "string" } }, "required": [ "prompt" ] }, "minItems": 1, "maxItems": 100 }, "task": { "type": "object", "properties": { "system": { "type": "string" }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 32000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } } }, "scorer": { "type": "object", "properties": { "type": { "enum": [ "none", "exact", "contains", "json" ] }, "case_sensitive": { "type": "boolean" } }, "required": [ "type" ] } }, "required": [ "models", "dataset" ] } } } }, "responses": { "200": { "description": "NDJSON: cell lines, then the summary.", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } }, "400": { "description": "A malformed body, named; more than 400 cells; an unknown scorer; or a scorer that needs `expected` where an item has none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/batches": { "post": { "operationId": "createBatch", "tags": [ "Batches" ], "summary": "Create a batch", "description": "Up to 10,000 chat-completion requests, run by the **provider's own batch API** -- OpenAI's Batch API, Anthropic's Message Batches, Google's Gemini batch mode, Mistral's batch jobs, Alibaba Model Studio's Batch API, xAI's Batch API -- at its batch price (the catalogue's `:batch` models, typically half the live price), within 24 hours, on your own provider key. Name the model (`openai/gpt-5.4` or `openai/gpt-5.4:batch`); every request uses it.\n\nEach request is `{custom_id, body}`, the body a chat completion without `model` or `stream`. The requests pass the same budgets, guardrails and content filters as live ones -- every message text is filtered, and what a filter redacts is what is submitted -- and the hold is the worst case of all of them. Server tools are refused: they run inside a live request.\n\nPoll `GET /v1/batches/{id}`; once it has ended it is billed, once, on the sum of its requests' usage at the batch price, and `GET /v1/batches/{id}/results` streams the outcomes. **Nothing of the requests or results is stored here**: the provider holds them, under your account, for its own retention.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this batch is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "A chat model with a `:batch` row in `/v1/models`, named with or without the suffix." }, "requests": { "type": "array", "items": { "type": "object", "properties": { "custom_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "body": { "type": "object" } }, "required": [ "custom_id", "body" ] }, "minItems": 1, "maxItems": 10000 }, "endpoint": { "enum": [ "/v1/chat/completions" ] }, "completion_window": { "enum": [ "24h" ] }, "provider": { "type": "object", "description": "Routing preferences, as on chat completions." } }, "required": [ "model", "requests" ] } } } }, "responses": { "200": { "description": "The batch, submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "description": "A malformed request, named by its index; a streamed or server-tool request; or a model with no batch row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A budget is exhausted, a content filter blocked a request, or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No model by that name, or no endpoint can serve it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited", "description": "Your key's request rate." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "The provider refused the batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listBatches", "tags": [ "Batches" ], "summary": "List batches", "description": "The organisation's batches, newest first, as last checked.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The batches.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Batch" } } } } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/batches/{id}": { "get": { "operationId": "getBatch", "tags": [ "Batches" ], "summary": "Get a batch", "description": "Its status, asking the provider when the last answer is over 30 seconds old. The first look after it has ended bills it -- once -- and `usage.cost` appears.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id (`batch_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/batches/{id}/results": { "get": { "operationId": "getBatchResults", "tags": [ "Batches" ], "summary": "Get a batch's results", "description": "JSON Lines, one per request, in OpenAI's batch output shape: `{custom_id, response: {status_code, body: }, error}`, or `{custom_id, response: null, error: {code, message}}`. Read from the provider as it is sent; nothing is kept.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The results.", "content": { "application/jsonl": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The batch has not ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/batches/{id}/cancel": { "post": { "operationId": "cancelBatch", "tags": [ "Batches" ], "summary": "Cancel a batch", "description": "Asks the provider to stop it. Requests already done are still billed when it ends.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "It has already ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/videos": { "post": { "operationId": "createVideo", "tags": [ "Videos" ], "summary": "Generate a video", "description": "OpenAI's video shape: submits a job and answers at once with a `video` object, `status: \"queued\"`. Poll `GET /v1/videos/{id}` until it is `completed` (or `failed`), then download `GET /v1/videos/{id}/content`. Generation takes minutes.\n\nRouted and admitted like every other call -- `model`, `models` and `provider` as on chat completions, the same budgets, content filters (a redacted prompt is what is generated) and guardrails -- with a hold sized at $0.60 a second of video asked for, then **billed on the provider's reported cost** of the generation, since video prices vary by resolution, audio and length. `seconds` (1 to 15) is sent in each model's own field; `parameters` carries the model's other fields as given (resolution, aspect ratio, negative prompt, seed...).\n\nOff unless the deployment sets `VIDEO_ENABLED=true`: a finished video is generated content stored for 24 hours, which waits on a privacy review; until then every video route is a 403 saying so.", "security": [ { "inferenceKey": [] }, { "session": [] } ], "parameters": [ { "name": "X-Autonomous-Relay-Agent", "in": "header", "required": false, "description": "The agent this request is for, as on chat completions.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "A text-to-video model id from `/v1/models`." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Fallbacks, tried in order after `model`." }, "prompt": { "type": "string", "maxLength": 4000 }, "seconds": { "type": "integer", "minimum": 1, "maximum": 15 }, "parameters": { "type": "object", "description": "The model's own fields, at most 30 and 8 KB; not `prompt` or `webhook`." }, "provider": { "type": "object", "description": "Routing preferences, as on chat completions." } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "The job, queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "400": { "description": "A malformed `prompt`, `seconds` or `parameters`; `model is required`; or the model is not a text-to-video model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "402": { "description": "Not enough credit for the hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Video generation is off on this deployment; a budget is exhausted; a content filter blocked the prompt; or the key is a management key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No model by that name, or no endpoint can serve it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/KeyRateLimited", "description": "Your account's request rate, the key's own `rpm_limit` or `tpm_limit`, or every candidate was rate limited upstream." }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Every candidate refused the job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listVideos", "tags": [ "Videos" ], "summary": "List videos", "description": "The organisation's jobs, newest first, as `{\"object\": \"list\", \"data\": [...]}`. Off unless the deployment sets `VIDEO_ENABLED=true`: a finished video is generated content stored for 24 hours, which waits on a privacy review; until then every video route is a 403 saying so.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } } } } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/videos/{id}": { "get": { "operationId": "getVideo", "tags": [ "Videos" ], "summary": "Get a video job", "description": "Its status -- `queued`, `in_progress`, `completed` or `failed` -- and, once known, what it cost. A job the provider has not reported on within two hours is failed and its hold given back.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The video id (`video_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteVideo", "tags": [ "Videos" ], "summary": "Delete a video", "description": "The job and its video. A job still being generated is a 409: its result is still due.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The video id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "enum": [ "video" ] }, "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Still being generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/videos/{id}/content": { "get": { "operationId": "getVideoContent", "tags": [ "Videos" ], "summary": "Download a video", "description": "The finished video, within 24 hours of its completion: the bytes as an attachment when the provider delivered them (stored encrypted), or a 302 to the provider's own link when it delivered one (the link is stored encrypted; the video stays with the provider). Follow redirects.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The video id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The video.", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "The provider's link to the video, in `Location`." }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not completed yet, or failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/videos/{id}/callback": { "post": { "operationId": "videoCallback", "tags": [ "Videos" ], "summary": "Receive a provider's video result", "description": "For the provider, not for you: the webhook a video job is submitted with. Authenticated by the job's secret `token` in the URL, compared in constant time against its hash; an unknown job or a wrong token is a bare 404. A delivery for a job already handled is acknowledged and changes nothing, so the provider's retries settle a job once.", "security": [ { "linkToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The video id.", "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": true, "description": "The job's callback secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "The provider's inference result." } } } }, "responses": { "200": { "description": "Accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/classifiers": { "get": { "operationId": "listClassifiers", "tags": [ "Classifiers" ], "summary": "List classifiers", "description": "Organisation rules that tag each request from content-free signals, in the order they run. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Classifier" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createClassifier", "tags": [ "Classifiers" ], "summary": "Create a classifier", "description": "Every enabled classifier whose conditions all hold gives the request its tag (stored on the request, shown in /v1/activity, sent back as `x-autonomous-relay-tags`). The first matching one that names a preset routes the request through it. Conditions read only content-free signals: the model the request named, the key, the client, the agent, the app, whether tools or images are present, streaming and the prompt's size. config:write.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "tag": { "type": "string", "description": "Lower-case letters, digits and hyphens, at most 40. Unique per organisation." }, "priority": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 100, "description": "Lower runs first; decides which matching classifier routes." }, "conditions": { "$ref": "#/components/schemas/ClassifierConditions" }, "preset": { "type": [ "string", "null" ], "description": "A preset slug to route a matching request through. A request naming its own @preset/… keeps it." }, "enabled": { "type": "boolean" } }, "required": [ "name", "tag", "conditions" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Classifier" } }, "required": [ "data" ] } } } }, "400": { "description": "A condition that is not one, an empty rule, `no preset named …`, or `at most 50 classifiers`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "A classifier with that tag exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/classifiers/{id}": { "put": { "operationId": "updateClassifier", "tags": [ "Classifiers" ], "summary": "Replace a classifier", "description": "Needs the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The classifier id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "tag": { "type": "string", "description": "Lower-case letters, digits and hyphens, at most 40. Unique per organisation." }, "priority": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 100, "description": "Lower runs first; decides which matching classifier routes." }, "conditions": { "$ref": "#/components/schemas/ClassifierConditions" }, "preset": { "type": [ "string", "null" ], "description": "A preset slug to route a matching request through. A request naming its own @preset/… keeps it." }, "enabled": { "type": "boolean" } }, "required": [ "name", "tag", "conditions" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Classifier" } }, "required": [ "data" ] } } } }, "400": { "description": "As for create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Another classifier has that tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteClassifier", "tags": [ "Classifiers" ], "summary": "Delete a classifier", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The classifier id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/classifiers/evaluate": { "post": { "operationId": "evaluateClassifiers", "tags": [ "Classifiers" ], "summary": "Try a sample request", "description": "Which classifiers a request with these signals would match, and which would route it. Nothing is sent.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "key_name": { "type": "string" }, "workspace_id": { "type": "string" }, "agent": { "type": "string" }, "app": { "type": "string" }, "has_tools": { "type": "boolean" }, "has_images": { "type": "boolean" }, "stream": { "type": "boolean" }, "prompt_tokens": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "route": { "type": [ "object", "null" ], "properties": { "tag": { "type": "string" }, "preset": { "type": "string" } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/tools": { "get": { "operationId": "listServerTools", "tags": [ "Tools" ], "summary": "List server tools", "description": "Every server tool in the catalogue (§11.2), whether it is available yet, whether it sends request data to a third party, and whether this organisation has it on. Any role may read this. The catalogue is the gateway's own tools; a connection's tools (`autonomousrelay:plugin`, `autonomousrelay:mcp`, and `autonomousrelay:connected` for all of them) are the organisation's, listed by GET /v1/tools/available.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServerTool" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "setServerTools", "tags": [ "Tools" ], "summary": "Turn server tools off or on", "description": "`disabled` is the full list of tools to turn off; every available tool not in it is on. A request declaring a tool that is off is refused with a 403 naming it. config:write.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "array", "items": { "type": "string", "description": "A server tool type, e.g. `autonomousrelay:datetime`." } } }, "required": [ "disabled" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServerTool" } } }, "required": [ "data" ] } } } }, "400": { "description": "`not an available server tool: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/tools/available": { "get": { "operationId": "listAvailableTools", "tags": [ "Tools" ], "summary": "List connected tools", "description": "Every connection of the key's organisation -- its installed plugins, then its MCP servers, each by name -- with whether it works now and the tools it offers, named as the model sees them: what `{\"type\": \"autonomousrelay:connected\"}` would draw on. Each connection is asked live, in parallel, within 5 seconds. `status` is `ok`, `not_connected` (an OAuth plugin never connected), `expired` (its connection lapsed: reconnect it), `disabled` (turned off for the organisation) or `unreachable` (it did not answer). A plugin that could not be asked shows its stored manifest's tools (`tools_source: \"manifest\"`, no descriptions); an MCP server that could not be asked shows none. `mode` is `read` only when the tool says it is read-only and, for a plugin, its manifest agrees. 30 requests a minute per key.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/presets": { "get": { "operationId": "listPresets", "tags": [ "Presets" ], "summary": "List presets", "description": "Each preset's current version. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Preset" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createPreset", "tags": [ "Presets" ], "summary": "Create a preset", "description": "A named set of request SETTINGS, used as `\"model\": \"@preset/\"` in a completion (or `@preset/@` to pin one). `body` holds settings only — `model`, `models`, `temperature`, `top_p`, `top_k`, `max_tokens`, `seed`, `provider`, `reasoning`, `routing_stability` — never messages or a system prompt. A whole request body is accepted: other fields are dropped, named in `dropped`, and never stored. config:write.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "Lower-case letters, digits and hyphens, at most 64." }, "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "object", "properties": {} } }, "required": [ "slug", "name", "body" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Preset" }, { "type": "object", "properties": { "dropped": { "type": "array", "items": { "type": "string" } } } } ] } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range, a slug that is not one, or `at most 100 presets`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "A preset with that slug exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/presets/{slug}": { "get": { "operationId": "getPreset", "tags": [ "Presets" ], "summary": "Get a preset and its history", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The preset slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Preset" }, { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "body": { "type": "object", "properties": {} }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updatePreset", "tags": [ "Presets" ], "summary": "Save a new version", "description": "Every change is a new version; versions are never edited. config:write.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The preset slug.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "object", "properties": {} }, "note": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Preset" } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deletePreset", "tags": [ "Presets" ], "summary": "Delete a preset and its history", "description": "A request still naming it is then a 404. config:write.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The preset slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "slug": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/presets/{slug}/restore": { "post": { "operationId": "restorePreset", "tags": [ "Presets" ], "summary": "Make an old version current again", "description": "As a new version with the old one's body, so the history keeps what happened. config:write.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The preset slug.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer" } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Preset" } }, "required": [ "data" ] } } } }, "400": { "description": "`version must be a version number`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/broadcast": { "get": { "operationId": "listBroadcastDestinations", "tags": [ "Observability" ], "summary": "List broadcast destinations", "description": "Where a record of each completion is sent (§14.12 Observability). Never returns a signing secret or a header value; `header_hint` is the value's last four characters. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastDestination" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createBroadcastDestination", "tags": [ "Observability" ], "summary": "Add a broadcast destination", "description": "After every completion, a record of the request is sent to each destination — **metadata only**: model, provider, status, tokens, cost, timing, key name, client, agent, session and run; never the prompt or the completion.\n\n`webhook`: a JSON POST `{\"type\":\"request.completed\",\"request\":{…}}`, signed with `X-AgentsRouter-Signature` (`t=…,v1=hmac_sha256(secret, t + \".\" + body)`); the signing secret is returned once, here. `otlp`: one OpenTelemetry span per request (OTLP/HTTP JSON, `gen_ai.*` attributes) to the URL given, which is the full traces endpoint, e.g. `https://api.honeycomb.io/v1/traces`; `header_name` and `header_value` carry the vendor's API key, sealed at rest and never shown again. `s3`: S3-compatible object storage (AWS S3, Cloudflare R2, Backblaze B2, MinIO, Google Cloud Storage with HMAC keys). `url` is the endpoint without a bucket, e.g. `https://s3.us-east-1.amazonaws.com`; records are batched — up to 500 records, 4 MB, or 60 seconds — and each batch is one newline-delimited JSON object (each line the webhook's `request.completed` record) at `{s3_prefix}{YYYY}/{MM}/{DD}/{HH}/{timestamp}-{random}.jsonl`, UTC, signed with AWS Signature Version 4. The key needs only `s3:PutObject` on the bucket; `s3_secret_access_key` is sealed at rest and never shown again.\n\n`langfuse`: each request becomes a Langfuse trace with one generation (model, token usage, cost, latency, time to first token, level), sent over OTLP/HTTP JSON to `{url}/api/public/otel/v1/traces` with Basic auth from `langfuse_public_key` and `langfuse_secret_key`; batched up to 100 records or 10 seconds. `datadog`: each request becomes a log (`service:autonomousrelay`, `ddsource:autonomousrelay`, `ddtags` `model:…,provider:…,status:…`, the `request` record as attributes) sent to `https://http-intake.logs.{datadog_site}/api/v2/logs` with `DD-API-KEY`; batched up to 500 records or 10 seconds. Both carry metadata only — no prompt or completion.\n\nThe URL must be public https. At most 10 destinations; `sample_rate` sends that fraction of requests. Delivery is after the response, never on the request path. A transient failure (a network error, HTTP 429 or 5xx) is retried up to 3 attempts in all with jittered exponential backoff; any other refusal is final. The final outcome is recorded on the destination (`last_error`).", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "webhook", "otlp", "s3", "langfuse", "datadog" ] }, "url": { "type": "string", "description": "Public https. For `s3`, the storage endpoint without a bucket or path. For `langfuse`, the Langfuse host (default `https://cloud.langfuse.com`; e.g. `https://us.cloud.langfuse.com` or a self-hosted URL). Not for `datadog`, whose intake is derived from `datadog_site`." }, "name": { "type": "string" }, "header_name": { "type": "string", "description": "webhook and otlp: an HTTP header to send, e.g. `x-honeycomb-team` or `Authorization`." }, "header_value": { "type": "string", "description": "Its value. Sealed at rest; only the last four characters are shown again." }, "sample_rate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "default": 1 }, "s3_region": { "type": "string", "description": "s3, required: the signing region, e.g. `us-east-1`; `auto` for Cloudflare R2." }, "s3_bucket": { "type": "string", "description": "s3, required: the bucket name." }, "s3_prefix": { "type": "string", "description": "s3: prepended to every object key, e.g. `relay/prod/`. At most 256 characters." }, "s3_path_style": { "type": "boolean", "description": "s3: `https://endpoint/bucket/key` rather than `https://bucket.endpoint/key`. Defaults to false for `*.amazonaws.com`, true elsewhere; a bucket with dots needs true." }, "s3_access_key_id": { "type": "string", "description": "s3, required." }, "s3_secret_access_key": { "type": "string", "description": "s3, required. Sealed at rest; only the last four characters are shown again." }, "langfuse_public_key": { "type": "string", "description": "langfuse, required: the project's public key, `pk-lf-…`." }, "langfuse_secret_key": { "type": "string", "description": "langfuse, required: the project's secret key, `sk-lf-…`. Sealed at rest; only the last four characters are shown again." }, "datadog_site": { "enum": [ "datadoghq.com", "us3.datadoghq.com", "us5.datadoghq.com", "datadoghq.eu", "ap1.datadoghq.com", "ap2.datadoghq.com", "uk1.datadoghq.com", "ddog-gov.com", "us2.ddog-gov.com" ], "default": "datadoghq.com", "description": "datadog: the Datadog site of the organisation." }, "datadog_api_key": { "type": "string", "description": "datadog, required: a Datadog API key (32 hexadecimal characters). Sealed at rest; only the last four characters are shown again." } }, "required": [ "kind", "url" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/BroadcastDestination" }, { "type": "object", "properties": { "signing_secret": { "type": "string", "description": "webhook only, returned once." } } } ] } }, "required": [ "data" ] } } } }, "400": { "description": "An unsafe URL, a reserved header, an incomplete or invalid `s3_*`, `langfuse_*` or `datadog_*` field, `at most 10 destinations`, or `unknown field: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "`secret storage is not configured on this deployment`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcast/{id}": { "patch": { "operationId": "updateBroadcastDestination", "tags": [ "Observability" ], "summary": "Pause, resume, rename or resample a destination", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The destination id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean" }, "sample_rate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "name": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BroadcastDestination" } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range, or `unknown field: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteBroadcastDestination", "tags": [ "Observability" ], "summary": "Remove a destination", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The destination id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/broadcast/{id}/test": { "post": { "operationId": "testBroadcastDestination", "tags": [ "Observability" ], "summary": "Send a test record now", "description": "A synthetic request record, marked as a test, delivered at once; the answer says how the receiver responded. Sent once, without retries. For `s3`, `langfuse` and `datadog`, a batch of that one record is sent straight away, not buffered.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The destination id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "http_status": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/marketplace/plugins": { "get": { "operationId": "listMarketplacePlugins", "tags": [ "Plugins" ], "summary": "List the plugin marketplace", "description": "Public and rate limited. Every approved plugin: what it is, who publishes it, how an install authenticates (`none`, `api_key` or `oauth2`), its categories and logo. Not where it runs.", "security": [], "x-auth": "public", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PluginListing" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/marketplace/plugins/{slug}": { "get": { "operationId": "getMarketplacePlugin", "tags": [ "Plugins" ], "summary": "One approved plugin", "description": "Its listing and, for a connector, what it does: the tools it offers (`write` ones wait for approval), the events it sends and what it keeps where.", "security": [], "x-auth": "public", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The plugin's slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PluginDetail" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/marketplace/plugins/{slug}/icon": { "get": { "operationId": "getMarketplacePluginIcon", "tags": [ "Plugins" ], "summary": "An approved plugin's logo", "description": "Public. The image itself, under its own type, cached a day; the listing's `icon_url` changes when the logo does.", "security": [], "x-auth": "public", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The plugin's slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The image.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugins": { "get": { "operationId": "listMyPlugins", "tags": [ "Plugins" ], "summary": "List the plugins your organisation publishes", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plugin" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createPlugin", "tags": [ "Plugins" ], "summary": "Register a plugin", "description": "A plugin is an MCP server you host (Streamable HTTP, public https). It starts private: your organisation can install and use it at once to build and test it; submit it for review to be listed publicly. One a super admin registers is the platform's own and is listed for every organisation at once. `auth: api_key` means each installing organisation pastes a key you give them, sent in `auth_header` (default Authorization). Agent tools -- tools that run many steps on your side and answer once -- are called like any tool, with up to 120 seconds per call. At most 20 plugins per organisation.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginInput" } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Plugin" } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range, an unsafe URL, or `unknown field: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "The slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugins/{id}": { "patch": { "operationId": "updatePlugin", "tags": [ "Plugins" ], "summary": "Edit a plugin you publish", "description": "Any listing field but the slug. Sending `publisher`, `mcp_url`, `auth`, `auth_header` or an `oauth_*` field sends an approved plugin back to review -- unlisted, and unusable by other organisations, until approved again -- unless a super admin sends it. A logo or a client secret alone never does.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plugin id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Plugin" } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range, or the slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deletePlugin", "tags": [ "Plugins" ], "summary": "Delete a plugin you publish", "description": "Every installation of it goes with it.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plugin id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugins/{id}/icon": { "get": { "operationId": "getMyPluginIcon", "tags": [ "Plugins" ], "summary": "The logo of a plugin you publish", "description": "Listed or not, as its `icon_url` in your own list points to. usage:read.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plugin id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The image.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugins/{id}/manifest": { "post": { "operationId": "refreshPluginManifest", "tags": [ "Plugins" ], "summary": "Read the plugin's connector manifest", "description": "Fetches `/.well-known/autonomousrelay-connector.json` from the plugin's MCP origin through the SSRF guard, checks it, and stores it: capabilities, each tool's mode (a tool counts as read-only only if this and its `readOnlyHint` both say so) and context keys, the events it sends, its `handshake_url` (on its own origin, required when it sends events) and what it stores. The plugin's owner, config:write.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plugin id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConnectorManifest" } }, "required": [ "data" ] } } } }, "400": { "description": "No manifest, or one that is not valid; the message says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugin-installs/{id}/handshake": { "post": { "operationId": "handshakePluginInstall", "tags": [ "Plugins" ], "summary": "Give a connector install a new events token", "description": "The gateway mints an events token and POSTs `{install_id, events_url, events_token}` to the manifest's `handshake_url` with the install's own credential, as tool calls carry it. Done at install; this retries after a failure or rotates the token. The old token works until the connector accepts the new one. config:write.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The install id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "events_ready": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "The connector did not accept it; the message says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors/events": { "post": { "operationId": "postConnectorEvent", "tags": [ "Plugins" ], "summary": "Post an event from a connector", "description": "For connectors: `Authorization: Bearer ` from the install handshake. The event must be one the manifest declares, with only its declared context keys and field names; `id` is the platform's own event id, and a repeat within a day answers `200 {duplicate: true}`. Each active `plugin_event` trigger of the install and type starts a run, as its own key and inside its own caps. Nothing is stored but the id. Off unless the deployment sets `HOSTED_AGENTS_ENABLED=true`.", "security": [ { "connectorEventsToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "e.g. order.created" }, "id": { "type": "string", "description": "The platform's event id." }, "occurred_at": { "type": "string", "format": "date-time" }, "context": { "type": "object", "additionalProperties": { "type": "string" } }, "fields": { "type": "object", "properties": {} } }, "required": [ "type", "id" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "duplicate": { "type": "boolean" }, "id": { "type": "string" } } } }, "required": [ "data" ] } } } }, "202": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "runs": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "trigger": { "type": "string" }, "reason": { "type": "string" } } } } } } }, "required": [ "data" ] } } } }, "400": { "description": "An undeclared type, context key or field, or fields over 32 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No events token, or one that names no enabled install.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Hosted agents are not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugins/{id}/submit": { "post": { "operationId": "submitPlugin", "tags": [ "Plugins" ], "summary": "Submit a plugin for review", "description": "It waits in the queue for a super admin. A super admin's own submission is listed for every organisation at once, as Official.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plugin id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Plugin" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Only a private or rejected plugin can be submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugins/{id}/install": { "post": { "operationId": "installPlugin", "tags": [ "Plugins" ], "summary": "Install a plugin for your organisation", "description": "`{id}` is the plugin's slug. An approved plugin, or one your organisation publishes. For an `api_key` plugin, `credential` is the key its developer gave you: sealed at rest, sent only to the plugin, only its last four characters shown again. Then offer it in a request with `{\"type\": \"autonomousrelay:plugin\", \"plugin\": \"\"}` in `tools`. The plugin is a recipient you choose: it receives the tool arguments the model writes.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plugin's slug.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "string" } } } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PluginInstall" } }, "required": [ "data" ] } } } }, "400": { "description": "A missing or unexpected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Installed already.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "`secret storage is not configured on this deployment`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plugins/{id}/connect": { "post": { "operationId": "connectPlugin", "tags": [ "Plugins" ], "summary": "Start connecting an OAuth plugin", "description": "`{id}` is the plugin's slug. For an `oauth2` plugin: the answer's `authorize_url` is the plugin developer's sign-in page (authorization code + PKCE S256); send the person there. Their authorization server returns them to `/v1/auth/oauth/plugin/callback`, which stores the tokens on your organisation's install (sealed, refreshed before they expire) and sends them back to the dashboard. Whatever the plugin reaches upstream -- a Google account, say -- is granted to its developer there, never to us.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plugin's slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorize_url": { "type": "string" } }, "required": [ "authorize_url" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/oauth/plugin/callback": { "get": { "operationId": "pluginOAuthCallback", "tags": [ "Plugins" ], "summary": "Where a plugin's authorization server returns", "description": "Not called directly. Checks the state against the flow cookie, redeems the code with the PKCE verifier (and the plugin's client secret, if it has one), stores the tokens, and redirects to the dashboard with `connected=` or `plugin_error=`. Register `{PUBLIC_ORIGIN}/v1/auth/oauth/plugin/callback` as the redirect URI.", "security": [], "x-auth": "The `state` matched to the flow cookie, and the plugin authorization server's code, redeemed with the PKCE verifier.", "responses": { "302": { "description": "Back to the dashboard." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugins/{id}/tools": { "get": { "operationId": "listInstalledPluginTools", "tags": [ "Plugins" ], "summary": "An installed plugin's tools, live", "description": "`{id}` is the plugin's slug. Asks the plugin now (`tools/list`) on your install's credential: the way to check an install works.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plugin's slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "input_schema": { "type": "object", "additionalProperties": true } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "The plugin could not be reached, refused the key, or answered with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plugin-installs": { "get": { "operationId": "listPluginInstalls", "tags": [ "Plugins" ], "summary": "Your organisation's installed plugins", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PluginInstall" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/plugin-installs/{id}": { "patch": { "operationId": "updatePluginInstall", "tags": [ "Plugins" ], "summary": "Turn an installed plugin off or on", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The install id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "400": { "description": "`unknown field: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "uninstallPlugin", "tags": [ "Plugins" ], "summary": "Uninstall a plugin", "description": "Its sealed credential goes with it.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The install id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Uninstalled." }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mcp-servers": { "get": { "operationId": "listMcpServers", "tags": [ "Tools" ], "summary": "List registered MCP servers", "description": "Your organisation's own MCP servers (§17.7), whose tools a request can offer the model with `{\"type\": \"autonomousrelay:mcp\", \"server\": \"\"}`. Never returns the credential; `header_hint` is its last four characters. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/McpServer" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createMcpServer", "tags": [ "Tools" ], "summary": "Register an MCP server", "description": "An MCP server reachable over the Streamable HTTP transport, at a public https URL. `header_name` and `header_value` are the credential it expects (e.g. `Authorization: Bearer …`), sealed at rest and sent only on calls to it. `allowed_tools` limits which of its tools may ever be offered. Owner and Admin only (`config:write`); at most 20.\n\nThe server receives the tool arguments the model writes, which come from your conversation: it is a recipient you choose.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "1–32 lowercase letters, digits or hyphens: what a request names it by." }, "url": { "type": "string", "description": "Public https; the MCP endpoint itself." }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "header_name": { "type": "string", "description": "A header such as `Authorization` or `X-Api-Key`; not one the transport uses." }, "header_value": { "type": "string", "description": "Its value. Sealed at rest; only the last four characters are shown again." } }, "required": [ "name", "url" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/McpServer" } }, "required": [ "data" ] } } } }, "400": { "description": "An unsafe URL, a reserved header, `at most 20 MCP servers`, or `unknown field: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "A server with that name exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "`secret storage is not configured on this deployment`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/mcp-servers/{id}": { "patch": { "operationId": "updateMcpServer", "tags": [ "Tools" ], "summary": "Turn a registered MCP server off or on", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The server id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean" } }, "required": [ "disabled" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/McpServer" } }, "required": [ "data" ] } } } }, "400": { "description": "`unknown field: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteMcpServer", "tags": [ "Tools" ], "summary": "Remove a registered MCP server", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The server id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mcp-servers/{id}/tools": { "get": { "operationId": "listMcpServerTools", "tags": [ "Tools" ], "summary": "List a registered server's tools, live", "description": "Asks the server now (`tools/list`), narrowed to its `allowed_tools`: the way to check a registration works.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The server id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "input_schema": { "type": "object", "additionalProperties": true } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "The server could not be reached, refused the credential, or answered with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/routing": { "get": { "operationId": "getRoutingDefaults", "tags": [ "Guardrails" ], "summary": "Get the account routing defaults", "description": "The default model, fallback models and default provider sort for every key in the organisation. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoutingDefaults" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "setRoutingDefaults", "tags": [ "Guardrails" ], "summary": "Set the account routing defaults", "description": "Replaces the whole set; an omitted field is cleared. Owner and Admin only (`org:write`).\n\n`default_model` is used when a request names no model (otherwise a 400). `fallback_models` are tried, in order, after the models a request names, within the same depth of three a request's own `models` chain gets. `default_sort` applies when a request sets no `provider.sort`; with `lock_sort`, a request's own sort is ignored. None of these widen what a key may reach: every model still passes guardrails, the privacy policy and BYOK. Every model must be a listed, ready model id.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingDefaultsInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoutingDefaults" } }, "required": [ "data" ] } } } }, "400": { "description": "`not a listed model: …`, `default_sort must be one of: price, throughput, latency`, `lock_sort needs a default_sort to lock`, or `unknown field: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/ip-allowlist": { "get": { "operationId": "getIpAllowlist", "tags": [ "Guardrails" ], "summary": "Get the IP allowlist", "description": "§10.3. The CIDR ranges every key in the organisation must call from, and the address the gateway sees for this request. Empty is off. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cidrs": { "type": "array", "items": { "type": "string" } }, "your_address": { "type": "string", "description": "This request's address, as the allowlist is checked against it." } }, "required": [ "cidrs", "your_address" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "setIpAllowlist", "tags": [ "Guardrails" ], "summary": "Set the IP allowlist", "description": "Replaces the list. Owner and Admin only (`org:write`). Up to 100 ranges, IPv4 or IPv6; a bare address is a single host, and an address with host bits set past its prefix (`10.0.0.1/8`) is refused as a likely typo. `[]` turns the allowlist off.\n\nWhile the list is not empty, every key of the organisation — inference and management, `Authorization` or `x-api-key`, and dashboard sessions — is refused from any other address with **403 `ip_not_allowed`**, naming the address. **A list that does not include the address saving it is a 400**, so a change can never lock out the key making it. Takes effect at once on the instance serving the call and within 10 seconds everywhere else.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cidrs": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "CIDR ranges, e.g. `203.0.113.0/24` or `2001:db8::/32`." } }, "required": [ "cidrs" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cidrs": { "type": "array", "items": { "type": "string" } }, "your_address": { "type": "string" } }, "required": [ "cidrs", "your_address" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`cidrs[i] is not a CIDR range …`, `at most 100 ranges`, `unknown field: …`, or a list that does not include the caller's own address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/privacy": { "get": { "operationId": "getPrivacyPolicy", "tags": [ "Guardrails" ], "summary": "Get the account privacy policy", "description": "The account level of the org → workspace → key chain (§4.2, §10.3), with the eligibility preview for it and the regions endpoints declare. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/PrivacyPolicy" }, "eligibility": { "$ref": "#/components/schemas/Eligibility" }, "regions": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "setPrivacyPolicy", "tags": [ "Guardrails" ], "summary": "Set the account privacy policy", "description": "Replaces the whole policy; an omitted field is off. Owner and Admin only (`org:write`). It can only tighten routing for every key in the organisation: `regions` intersects with guardrails' `allowed_data_regions`, and an endpoint that declares no region fails it. `zdr`, `zdr_groups` and `deny_training` were removed: we do not record providers' retention or training terms, which are set by your own agreement with the provider. They are accepted switched off and refused switched on. Unknown fields are a 400.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyPolicyInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/PrivacyPolicy" }, "eligibility": { "$ref": "#/components/schemas/Eligibility" } } } }, "required": [ "data" ] } } } }, "400": { "description": "`unknown field: …`, a non-boolean flag, or a list that is not slugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/privacy/preview": { "post": { "operationId": "previewPrivacyPolicy", "tags": [ "Guardrails" ], "summary": "Preview a privacy policy before saving it", "description": "How many models stay available under the policy in the body, and which do not and why. Nothing is saved. Policy only: BYOK credentials and guardrails narrow further per key.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyPolicyInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Eligibility" } }, "required": [ "data" ] } } } }, "400": { "description": "As for PUT /v1/privacy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/logging": { "get": { "operationId": "getContentLogging", "tags": [ "Guardrails" ], "summary": "Get input/output logging settings", "description": "§13.1. An organisation that has never configured this gets the defaults: **off**, 90-day retention, consented to `self_access` only.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContentLoggingSettings" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "setContentLogging", "tags": [ "Guardrails" ], "summary": "Configure input/output logging", "description": "Management key only: an inference key must not be able to change what is recorded about its own traffic.\n\n**`enabled: true` is refused in this release.** It is gated on the review of `PIA-2026-001`, whose adequacy conclusion depends on prompt content not being stored. Every other field configures now.\n\n`locked: true` freezes the settings; further changes are refused until it is cleared — and changing the setting needs the Owner or Developer role (a management key with no person behind it has full power).", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Refused when true in this release." }, "key_include": { "type": "array", "items": { "type": "string" }, "description": "Key hashes to capture. Empty means every key." }, "key_exclude": { "type": "array", "items": { "type": "string" }, "description": "**Exclusion wins** over inclusion — a key in both is not captured." }, "retention_days": { "type": "integer", "minimum": 90, "description": "§13.1's ~3-month floor." }, "locked": { "type": "boolean" }, "purposes": { "type": "array", "items": { "enum": [ "self_access", "rag" ] }, "description": "What the organisation consents to. Must include `self_access`; to stop storing, disable logging instead. Consent is purpose-specific — agreeing that we store your prompts so **you** can replay them is not agreeing that we may index them." } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContentLoggingSettings" } }, "required": [ "data" ] } } } }, "400": { "description": "A refused `enabled: true`, a locked organisation, a retention below the floor, or an unknown purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/credits": { "get": { "operationId": "getCredits", "tags": [ "Credits" ], "summary": "Get the balance", "description": "Held credits are reserved by requests in flight and are shown apart from the available balance.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Credits" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/credits/fees": { "get": { "operationId": "getCreditFees", "tags": [ "Credits" ], "summary": "Get the purchase fee schedule", "description": "Public. While nothing a credit can buy exists (BYOK-only), `purchasable` is false and the fee is reported as 0.", "security": [], "x-auth": "public", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "fee_bps": { "type": "integer", "description": "Basis points." }, "fee_min": { "type": "number", "description": "US dollars." }, "min_purchase": { "type": "number", "description": "US dollars." }, "configured": { "type": "boolean", "description": "A payment processor is configured." }, "purchasable": { "type": "boolean", "description": "A purchased balance could actually be spent." } } } }, "required": [ "data" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/credits/history": { "get": { "operationId": "listCreditPurchases", "tags": [ "Credits" ], "summary": "List purchases", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Opaque; do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of purchases.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPurchase" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`cursor is malformed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/credits/purchases/{id}/invoice": { "get": { "operationId": "getPurchaseDocument", "tags": [ "Credits" ], "summary": "Get a purchase's invoice or receipt", "description": "Resolved from Stripe on demand; only the checkout session id is stored.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A purchase `id`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "kind": { "enum": [ "invoice", "receipt" ] }, "url": { "type": "string" }, "pdf_url": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "No such purchase, or it has no Stripe document." }, "409": { "description": "The document is not ready yet; try again shortly. The body reports `code: 400`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Stripe could not be reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Billing is not configured on this deployment (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/billing/plan": { "get": { "operationId": "getPlan", "tags": [ "Billing" ], "summary": "The organisation's plan", "description": "`trial` (Team's features) for 14 days from creation; then the paid plan while its subscription is `active`, `trialing` or `past_due` (Stripe retrying a renewal): `pro` ($29/month: guardrails, usage alerts, exports, presets, classifiers), `team` ($99: Pro plus members, more workspaces and client reports), `business` ($399: Team plus SSO and SCIM), or `enterprise` (an invoiced annual contract, set up per customer in Stripe with `tier: enterprise` in the subscription metadata); `limited` otherwise. Each plan includes the ones before it. A feature the plan does not include answers 402 `subscription_required` when created or changed, naming the plan it needs; what was set up keeps working. Readable by every role.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "state": { "enum": [ "trial", "pro", "team", "business", "enterprise", "limited" ] }, "trial_ends_at": { "type": "string", "format": "date-time" }, "trial_days_left": { "type": "integer" }, "subscription": { "type": [ "object", "null" ], "description": "`{ status, current_period_end }` once the organisation has subscribed; Stripe's own status word." }, "price": { "type": "object", "properties": { "amount_usd": { "type": "integer" }, "interval": { "enum": [ "month" ] }, "per": { "enum": [ "organisation" ] } }, "description": "This plan's monthly price; Team's while the organisation has no self-serve plan." }, "plans": { "type": "array", "description": "Every plan the organisation can subscribe to, cheapest first.", "items": { "type": "object", "properties": { "tier": { "enum": [ "pro", "team", "business" ] }, "amount_usd": { "type": "integer" }, "interval": { "enum": [ "month" ] }, "per": { "enum": [ "organisation" ] } } } }, "configured": { "type": "boolean", "description": "False when STRIPE_SECRET_KEY is unset: subscribing answers 503." } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/billing/subscribe": { "post": { "operationId": "subscribe", "tags": [ "Billing" ], "summary": "Subscribe to a plan", "description": "Returns a Stripe Checkout URL for the plan named in `plan` -- `pro` ($29), `team` ($99, the default) or `business` ($399) a month, per organisation, card only. The plan changes when Stripe's webhook confirms the payment, not when this URL is created. Owner, Admin or Finance.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "enum": [ "pro", "team", "business" ], "description": "Defaults to `team`." } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "`plan` is not one of `pro`, `team`, `business`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "Already on a paid plan: change it with POST /v1/billing/change-plan (Enterprise: by contract).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Stripe could not start the checkout; nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Billing is not configured (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/billing/change-plan": { "post": { "operationId": "changePlan", "tags": [ "Billing" ], "summary": "Change plan", "description": "Moves a live Pro, Team or Business subscription to another of the three. The new price is prorated on the next invoice. Answers 202: the plan changes when Stripe's `customer.subscription.updated` arrives, usually within seconds. Enterprise is set by contract and is not changed here. Owner, Admin or Finance.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "enum": [ "pro", "team", "business" ] } }, "required": [ "plan" ] } } } }, "responses": { "202": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "enum": [ "pro", "team", "business" ] }, "status": { "enum": [ "pending" ] }, "note": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "`plan` is not one of `pro`, `team`, `business`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "No paid plan to change yet, already on that plan, or on Enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Stripe could not change the plan; nothing was changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Billing is not configured (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/billing/portal": { "post": { "operationId": "billingPortal", "tags": [ "Billing" ], "summary": "Open the billing portal", "description": "Returns a Stripe billing portal URL: the card, invoices, and cancelling. Owner, Admin or Finance.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "The organisation has never subscribed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "Stripe could not open the portal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Billing is not configured (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/credits/checkout": { "post": { "operationId": "createCheckout", "tags": [ "Credits" ], "summary": "Start a credit purchase", "description": "Returns a Stripe Checkout URL. **Refused with 409 while credits cannot be spent** (BYOK-only, zero fee) -- checked before the body is read.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 2, "maximum": 50000, "description": "USD." } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "fee": { "type": "number", "description": "US dollars." } } } }, "required": [ "data" ] } } } }, "400": { "description": "`amount must be at least $2`, or no greater than $50,000.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "Credits cannot be purchased while nothing can spend them. The body reports `code: 400`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Billing is not configured (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/stripe": { "post": { "operationId": "stripeWebhook", "tags": [ "Credits" ], "summary": "Receive a Stripe event", "description": "For Stripe, not for you. Credits on `checkout.session.completed` and `checkout.session.async_payment_succeeded` only when `payment_status` is `paid`, once per session; logs `async_payment_failed`; acknowledges everything else with 200.", "security": [ { "stripeSignature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "A Stripe event, verified against its raw bytes." } } } }, "responses": { "200": { "description": "Accepted. Not wrapped in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "const": true } }, "required": [ "received" ] } } } }, "400": { "description": "`Invalid signature`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "The webhook secret is not configured (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/status/uptime": { "get": { "operationId": "getUptimeHistory", "tags": [ "Status" ], "summary": "Measured uptime, last 90 days", "description": "From an external probe, not from traffic: a Cloud Monitoring uptime check requests /health (which queries the database) every minute from four regions. One entry per UTC day, oldest first. A day with fewer than 60 probes is `uptime: null` -- unmeasured, never counted as up. `overall` is over measured days, weighted by probes, and null when none is measured. Public, limited per client address, cached for a minute.", "security": [], "x-auth": "public", "responses": { "200": { "description": "The last 90 days.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "YYYY-MM-DD, UTC." }, "uptime": { "type": [ "number", "null" ], "description": "Share of probes that passed, 0 to 1." }, "checks": { "type": "integer" } } } }, "overall": { "type": [ "number", "null" ], "description": "0 to 1, over measured days." }, "measured_days": { "type": "integer" } } }, "source": { "type": "string" } } } } } }, "429": { "description": "Too many requests from this address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/status/incidents": { "get": { "operationId": "listStatusIncidents", "tags": [ "Status" ], "summary": "The incident log, last 90 days", "description": "Incidents posted by the operator, in English and French: those started in the last 90 days and any still open, newest first, each with its updates oldest first. `status` is the latest update's; `resolved_at` is set by the update that resolved it. Written by people, not inferred from the uptime probe. `subscriptions.email` says whether incident emails can be requested on this deployment. Public, limited per client address, cached for a minute.", "security": [], "x-auth": "public", "responses": { "200": { "description": "The incident log.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title_en": { "type": "string" }, "title_fr": { "type": "string" }, "impact": { "enum": [ "minor", "major", "critical" ] }, "status": { "enum": [ "investigating", "identified", "monitoring", "resolved" ] }, "started_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ] }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "enum": [ "investigating", "identified", "monitoring", "resolved" ] }, "body_en": { "type": "string" }, "body_fr": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "subscriptions": { "type": "object", "properties": { "email": { "type": "boolean" } } } } } } } }, "429": { "description": "Too many requests from this address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/status/incidents.atom": { "get": { "operationId": "getStatusIncidentFeed", "tags": [ "Status" ], "summary": "The incident log as an Atom feed", "description": "RFC 4287, one entry per update, newest first, over the same incidents as `/v1/status/incidents`. Follow the status page without giving an email address. Public and cached for a minute.", "security": [], "x-auth": "public", "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "`en` (default) or `fr`.", "schema": { "enum": [ "en", "fr" ] } } ], "responses": { "200": { "description": "The feed.", "content": { "application/atom+xml": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests from this address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/status/subscription": { "post": { "operationId": "subscribeStatusIncidents", "tags": [ "Status" ], "summary": "Ask to be emailed about incidents", "description": "Public; no account. Double opt-in: the address is sent one confirmation email, and nothing else until its link is clicked; an unconfirmed request is deleted after 7 days. Once confirmed, every incident and update posted afterwards is emailed once, in the chosen language, each with a one-click unsubscribe link. The answer is the same 202 whether or not an email was sent, so it says nothing about any address. Rate limited per client address and per email address.", "security": [], "x-auth": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The address to email." }, "lang": { "enum": [ "en", "fr" ], "description": "The language of the emails. Default `en`." } }, "required": [ "email" ] } } } }, "responses": { "202": { "description": "Check your inbox.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "enum": [ "check_inbox" ] }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`email` is not an email address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Email is not configured on this deployment (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/status/subscription/confirm": { "get": { "operationId": "confirmStatusSubscription", "tags": [ "Status" ], "summary": "Confirm an incident email subscription", "description": "The link in the confirmation email. Valid for 7 days, and idempotent while valid. Redirects to the status page with `subscription=confirmed`, or `subscription=invalid` for an unknown or expired link.", "security": [ { "linkToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "From the confirmation email.", "schema": { "type": "string" } } ], "responses": { "303": { "description": "To the status page, with the outcome.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/status/subscription/unsubscribe": { "get": { "operationId": "unsubscribeStatusIncidents", "tags": [ "Status" ], "summary": "Unsubscribe from incident emails (link)", "description": "The link in every incident email; no sign-in. Deletes the subscription and the address. Redirects to the status page with `subscription=unsubscribed`, or `subscription=invalid` for a link already used or unknown. Never refused by region: it only deletes.", "security": [ { "linkToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "From the email.", "schema": { "type": "string" } } ], "responses": { "303": { "description": "To the status page, with the outcome.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "unsubscribeStatusIncidentsOneClick", "tags": [ "Status" ], "summary": "Unsubscribe from incident emails (one-click, RFC 8058)", "description": "What a mail client POSTs to the `List-Unsubscribe` URL, with the body `List-Unsubscribe=One-Click` (form-encoded; ignored). The same deletion as the link.", "security": [ { "linkToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "From the email's List-Unsubscribe header.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "unsubscribed": { "type": "boolean" } }, "required": [ "unsubscribed" ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/branding": { "get": { "operationId": "getBranding", "tags": [ "Reports" ], "summary": "Report branding", "description": "The name, logo and footer printed on client reports in place of ours. Any role may read it.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "setBranding", "tags": [ "Reports" ], "summary": "Set report branding", "description": "Owner or Developer. Every field is optional; an absent or empty one clears it. The logo is a PNG or JPEG data URI under 150 KB, checked by its bytes: nothing is ever fetched from a URL, and SVG is refused.\n\nNeeds the Team ($99/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brand_name": { "type": [ "string", "null" ], "description": "Up to 80 characters." }, "brand_logo": { "type": [ "string", "null" ], "description": "`data:image/png;base64,...` or `data:image/jpeg;base64,...`, under 150 KB." }, "brand_footer": { "type": [ "string", "null" ], "description": "Up to 200 characters, e.g. a contact line." } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "required": [ "data" ] } } } }, "400": { "description": "A field too long, or a logo that is not a small PNG or JPEG.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/workspaces/{id}/report": { "get": { "operationId": "getWorkspaceReport", "tags": [ "Reports" ], "summary": "A client's month, as a report", "description": "Totals, by model, by agent and by day for one workspace in a UTC calendar month, with the branding to print it under. Amounts are list price -- what the tokens were worth, the number a client is re-billed on and the one budgets measure -- and the same measurement as the CSV export. A usage report, not an invoice: no tax, due date or markup.\n\nNeeds the Team ($99/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The workspace id.", "schema": { "type": "string" } }, { "name": "month", "in": "query", "required": false, "description": "YYYY-MM, UTC. Default: the current month.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "month": { "type": "string" }, "period": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" } } }, "branding": { "$ref": "#/components/schemas/Branding" }, "totals": { "$ref": "#/components/schemas/ReportLine" }, "by_model": { "type": "array", "items": { "$ref": "#/components/schemas/ReportLine", "description": "Plus `model`. Up to 50, largest first." } }, "by_agent": { "type": "array", "items": { "$ref": "#/components/schemas/ReportLine", "description": "Plus `agent`. Requests that named no agent are not listed." } }, "by_day": { "type": "array", "items": { "$ref": "#/components/schemas/ReportLine", "description": "Plus `day` (YYYY-MM-DD). Days with no traffic are absent." } }, "generated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] } } } }, "400": { "description": "`month must be YYYY-MM`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/audit-log": { "get": { "operationId": "listAuditLog", "tags": [ "Audit" ], "summary": "List the organisation's audit log", "description": "Who changed what, and when: keys created, revoked or re-limited; provider keys; guardrails; members invited, re-roled or removed; SSO, SCIM, broadcast, plugins, workspaces, alert channels and organisation settings. Newest first, keyset-paginated. Owner or Admin (a key with no person behind it has full power). The actor is a user id, or for a key with no person behind it the first 12 characters of the key's hash; `details` holds non-secret facts only -- never a key, a secret, an address or prompt content. Kept for one year.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Opaque; do not parse it.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "One action, e.g. `api_key.revoked`, or a category, e.g. `api_key`.", "schema": { "type": "string" } }, { "name": "actor", "in": "query", "required": false, "description": "A user id, or a key reference as the log shows it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "actor": { "type": "object", "properties": { "type": { "enum": [ "user", "api_key", "scim", "system" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "action": { "type": "string" }, "target": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "details": { "type": "object", "additionalProperties": true } } } }, "next_cursor": { "type": [ "string", "null" ] }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "A malformed `limit`, `before`, `action` or `actor`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/org": { "get": { "operationId": "getOrg", "tags": [ "Members" ], "summary": "Get the organisation", "description": "Its id, name, slug, plan, creation date and number of active seats. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Org" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "renameOrg", "tags": [ "Members" ], "summary": "Rename the organisation", "description": "Owner and Admin only (`org:write`). The name is what invitations and client reports show; the slug and id do not change. Trimmed, 1 to 80 characters, no control characters.", "security": [ { "managementKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Org" } }, "required": [ "data" ] } } } }, "400": { "description": "`name must not be empty`, `name must be at most 80 characters`, or `name must not contain control characters`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/cache": { "get": { "operationId": "getResponseCache", "tags": [ "Keys" ], "summary": "Describe the response cache", "description": "The organisation's live response-cache entries and their size. The cache is turned on per inference key (`cache_enabled`); `available` is false while the deployment does not run it, in which case nothing is cached whatever a key says.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "integer" }, "bytes": { "type": "integer", "description": "The size of the stored answers, before encryption." } }, "required": [ "available", "entries", "bytes" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "purgeResponseCache", "tags": [ "Keys" ], "summary": "Purge the response cache", "description": "Deletes every cached answer of the organisation at once; the next request of each kind is a miss. Owner and Admin only (`org:write`).", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "Entries deleted." } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/members": { "get": { "operationId": "listMembers", "tags": [ "Members" ], "summary": "List members", "description": "Everyone with an active seat in the organisation, owners first, and the caller's own role. Any role may read this, a seat limited to workspaces included.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The members.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "role": { "enum": [ "owner", "admin", "member", "billing", "readonly" ], "description": "owner = Owner, member = Developer, billing = Finance. What each may do: see the Members tag." }, "role_name": { "type": "string" }, "scope": { "enum": [ "org", "workspaces" ], "description": "`workspaces`: limited to the workspaces this person is a member of." }, "joined_at": { "type": "string", "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "is_you": { "type": "boolean" } } } }, "your_role": { "enum": [ "owner", "admin", "member", "billing", "readonly" ], "description": "owner = Owner, member = Developer, billing = Finance. What each may do: see the Members tag." } } } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/members/{userId}": { "patch": { "operationId": "changeMemberRole", "tags": [ "Members" ], "summary": "Change a member's role or scope", "description": "Owners only. Send `role`, `scope` or both. `scope: \"workspaces\"` limits a Developer or Read-only seat to the workspaces they are a member of (`PUT /v1/workspaces/{id}/members/{userId}`); with no memberships they see nothing, never the whole organisation. Owners, admins and Finance always see everything, so moving a seat to one of those roles sets its scope back to `org`. The organisation's last owner cannot be demoted (409).", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "The member's user id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "enum": [ "owner", "member", "billing" ] }, "scope": { "enum": [ "org", "workspaces" ], "description": "`workspaces`: limited to the workspaces this person is a member of." } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "string" }, "role": { "type": "string" }, "scope": { "enum": [ "org", "workspaces" ], "description": "`workspaces`: limited to the workspaces this person is a member of." } } } }, "required": [ "data" ] } } } }, "400": { "description": "An unknown role or scope, neither sent, or `workspaces` on a role that cannot be limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The last owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "removeMember", "tags": [ "Members" ], "summary": "Remove a member", "description": "Owners only. The seat is deactivated and the person's dashboard key in this organisation is revoked, ending their sessions here at once; their other organisations are untouched. The last owner cannot be removed (409).", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "The member's user id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "removed": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The last owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/invitations": { "get": { "operationId": "listInvitations", "tags": [ "Members" ], "summary": "Open invitations", "description": "Owners only. Invitations not yet accepted, revoked or expired. Links are not listed: only their hashes are kept.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "created_by_name": { "type": [ "string", "null" ] } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createInvitation", "tags": [ "Members" ], "summary": "Invite someone", "description": "Owners only. Returns a link, in this response and never again: single use, valid seven days, revocable. The invitee opens it, signs in, and accepts. At most 50 open invitations.\n\nNeeds the Team ($99/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "enum": [ "owner", "member", "billing" ] } }, "required": [ "role" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "description": "The invitation link. Store or send it now." } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/invitations/{id}": { "delete": { "operationId": "revokeInvitation", "tags": [ "Members" ], "summary": "Revoke an invitation", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invitation id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revoked": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/invitations/preview": { "post": { "operationId": "previewInvitation", "tags": [ "Members" ], "summary": "What an invitation is for", "description": "Public, limited per address. The token travels in the body to stay out of access logs. An unknown, used, revoked or expired token all answer the same 404.", "security": [], "x-auth": "The invitation token, in the body (kept out of URLs and access logs).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "org_name": { "type": "string" }, "role": { "type": "string" }, "role_name": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too many requests from this address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/invitations/accept": { "post": { "operationId": "acceptInvitation", "tags": [ "Members" ], "summary": "Accept an invitation", "description": "Requires a signed-in PERSON (a dashboard session); an API key has no seat and gets 403. Takes the seat, and replaces the session with one in the inviting organisation (Set-Cookie).", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "org_id": { "type": "string" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/orgs": { "get": { "operationId": "listMyOrganisations", "tags": [ "Auth" ], "summary": "The organisations I belong to", "description": "Every organisation the signed-in person has an active seat in, with their role and which one this session is in.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "role_name": { "type": "string" }, "current": { "type": "boolean" } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/switch": { "post": { "operationId": "switchOrganisation", "tags": [ "Auth" ], "summary": "Switch organisation", "description": "Moves the session into another organisation the person has a seat in (Set-Cookie). 404 for one they do not.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string" } }, "required": [ "org_id" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "org_id": { "type": "string" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/agents": { "get": { "operationId": "listAgents", "tags": [ "Agents" ], "summary": "List agents", "description": "Every agent named in `X-Autonomous-Relay-Agent` in the last 31 days, plus any with a budget but no traffic yet: requests and spend this UTC month (list price included, measured as an agent budget measures it) and budgets. Newest first; at most 500.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string" }, "last_seen": { "type": [ "string", "null" ], "format": "date-time" }, "requests_this_month": { "type": "integer" }, "spend_this_month": { "type": "number", "description": "US dollars." }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "interval": { "enum": [ "daily", "weekly", "monthly", "lifetime" ] }, "limit": { "type": "number", "description": "US dollars." }, "include_byok": { "type": "boolean" }, "mode": { "enum": [ "hard", "soft" ], "description": "`hard` refuses at the ceiling (403 `budget_exceeded`); `soft` serves, adds the sentence to `x-autonomous-relay-limit-warning`, and still alerts." }, "workspace_id": { "type": [ "string", "null" ], "description": "The client workspace this budget binds; null for the whole organisation." }, "workspace_name": { "type": [ "string", "null" ] } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/agents/definitions": { "get": { "operationId": "listAgentDefinitions", "tags": [ "Agents" ], "summary": "List hosted agents", "description": "Each saved agent's current version: model, tools and run caps. Never the instructions. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDefinition" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createAgentDefinition", "tags": [ "Agents" ], "summary": "Create a hosted agent", "description": "A saved agent: its instructions, the model or preset it runs on, the tools the gateway may run for it, and the caps every invocation opens a run under (`budget_usd`, `max_turns` and `max_tool_calls` are required). Run it with `POST /v1/agents/{slug}/invoke`. config:write. Off unless the deployment sets `HOSTED_AGENTS_ENABLED=true`: storing agent instructions waits on a privacy review, and until then this is a 403 saying so.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string", "description": "The system prompt, at most 32 KB. Sealed at rest; returned only to config:write." }, "model": { "type": "string", "description": "A model id or `@preset/`." }, "tools": { "type": "array", "items": { "type": "object", "properties": {}, "required": [ "type" ] }, "description": "Up to 8, each one the gateway runs: `autonomousrelay:plugin` (`plugin`, optional `allowed_tools`), `autonomousrelay:mcp` (`server`, optional `allowed_tools`), or a built server tool. A plain function is refused: nobody is standing by to run it." }, "run_defaults": { "type": "object", "properties": { "budget_usd": { "type": "number" }, "max_turns": { "type": "integer" }, "max_tool_calls": { "type": "integer" }, "max_cost_per_minute_usd": { "type": "number" }, "max_tool_calls_without_progress": { "type": "integer" }, "model_policy": { "type": "object", "properties": {} } }, "required": [ "budget_usd", "max_turns", "max_tool_calls" ] }, "approval": { "type": "object", "properties": { "mode": { "enum": [ "writes", "all", "none" ], "default": "writes" }, "expires_minutes": { "type": "integer", "minimum": 5, "maximum": 1440, "default": 1440 }, "never_ask": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } } }, "output": { "type": "object", "properties": { "destination_id": { "type": [ "string", "null" ] }, "schema": { "type": [ "object", "null" ] } } }, "slug": { "type": "string", "description": "Lower-case letters, digits and hyphens, at most 64." }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "slug", "name", "instructions", "model", "run_defaults" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentDefinition" } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range, a tool the gateway cannot run, a missing cap, or `at most 100 agents`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "409": { "description": "An agent with that slug exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/agents/definitions/{slug}": { "get": { "operationId": "getAgentDefinition", "tags": [ "Agents" ], "summary": "Get a hosted agent and its history", "description": "`instructions` is the current version's, and only for config:write; for any other role it is null.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The agent slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AgentDefinition" }, { "type": "object", "properties": { "instructions": { "type": [ "string", "null" ] }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "model": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": {} } }, "run_defaults": { "type": "object", "properties": {} } } } } } } ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateAgentDefinition", "tags": [ "Agents" ], "summary": "Save a new version", "description": "The whole body again; every change is a new version and versions are never edited, so a run always names what it ran under. config:write. Off unless the deployment sets `HOSTED_AGENTS_ENABLED=true`: storing agent instructions waits on a privacy review, and until then this is a 403 saying so.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The agent slug.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string", "description": "The system prompt, at most 32 KB. Sealed at rest; returned only to config:write." }, "model": { "type": "string", "description": "A model id or `@preset/`." }, "tools": { "type": "array", "items": { "type": "object", "properties": {}, "required": [ "type" ] }, "description": "Up to 8, each one the gateway runs: `autonomousrelay:plugin` (`plugin`, optional `allowed_tools`), `autonomousrelay:mcp` (`server`, optional `allowed_tools`), or a built server tool. A plain function is refused: nobody is standing by to run it." }, "run_defaults": { "type": "object", "properties": { "budget_usd": { "type": "number" }, "max_turns": { "type": "integer" }, "max_tool_calls": { "type": "integer" }, "max_cost_per_minute_usd": { "type": "number" }, "max_tool_calls_without_progress": { "type": "integer" }, "model_policy": { "type": "object", "properties": {} } }, "required": [ "budget_usd", "max_turns", "max_tool_calls" ] }, "approval": { "type": "object", "properties": { "mode": { "enum": [ "writes", "all", "none" ], "default": "writes" }, "expires_minutes": { "type": "integer", "minimum": 5, "maximum": 1440, "default": 1440 }, "never_ask": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } } }, "output": { "type": "object", "properties": { "destination_id": { "type": [ "string", "null" ] }, "schema": { "type": [ "object", "null" ] } } }, "name": { "type": "string" }, "description": { "type": "string" }, "note": { "type": "string", "description": "At most 200 characters." } }, "required": [ "instructions", "model", "run_defaults" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentDefinition" } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range, or `at most 200 versions`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "setAgentDefinitionStatus", "tags": [ "Agents" ], "summary": "Pause, resume or archive a hosted agent", "description": "A paused or archived agent refuses invocations with 409; its runs and versions stay. config:write.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The agent slug.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "active", "paused", "archived" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentDefinition" } }, "required": [ "data" ] } } } }, "400": { "description": "Not a status, or a field other than status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAgentDefinition", "tags": [ "Agents" ], "summary": "Delete a hosted agent", "description": "Deletes every version of its instructions and its triggers, and erases the paused state of any of its runs waiting on an approval, cancelling those runs. Its runs keep their record, without a link to the agent. config:write.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The agent slug.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "slug": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/agents/{slug}/invoke": { "post": { "operationId": "invokeAgent", "tags": [ "Agents" ], "summary": "Run a hosted agent", "description": "Opens a run under the agent's caps (an `overrides` value may lower `budget_usd`, `max_turns` or `max_tool_calls`, never raise one), sends its instructions and your `input` through `POST /v1/chat/completions` with its tools and `X-Autonomous-Relay-Agent` set to the slug, lets the gateway run the tool loop, closes the run and returns the answer. Everything a completion gets applies: presets, guardrails, routing, billing, agent budgets. With `stream: true` the answer streams as `POST /v1/chat/completions` does, between two SSE comments of the run's: `: autonomousrelay {\"type\": \"run.opened\", ...}` first and `{\"type\": \"run.closed\", \"run\": {...}}` just before `[DONE]`. Nothing is stored but the run's metadata. Off unless the deployment sets `HOSTED_AGENTS_ENABLED=true`: storing agent instructions waits on a privacy review, and until then this is a 403 saying so.", "security": [ { "inferenceKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The agent slug.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string", "description": "What the agent is asked to do, at most 100,000 characters." }, "overrides": { "type": "object", "properties": { "budget_usd": { "type": "number" }, "max_turns": { "type": "integer" }, "max_tool_calls": { "type": "integer" } } }, "stream": { "type": "boolean", "default": false } }, "required": [ "input" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentTurn" } }, "required": [ "data" ] } } } }, "202": { "description": "The run paused before a write: `status` is `awaiting_approval` and `approval` names the pending action. It continues when a person decides it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentTurn" } }, "required": [ "data" ] } } } }, "400": { "description": "No input, an unknown field, or an override above the definition's cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The agent is paused or archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "description": "The agent's run failed upstream; nothing was billed beyond what ran.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents/definitions/{slug}/triggers": { "get": { "operationId": "listAgentTriggers", "tags": [ "Agents" ], "summary": "List a hosted agent's triggers", "description": "Its webhooks and schedules. Never a signing secret. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The agent slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTrigger" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createAgentTrigger", "tags": [ "Agents" ], "summary": "Start a hosted agent from a webhook or a schedule", "description": "A `webhook` starts a run for each signed delivery to its `url`; a `schedule` every `every_minutes`. Runs are made as the inference key `key_hash` names -- billed, capped and tagged as that key's, and stopped by revoking or pausing it -- within the agent's run caps and the trigger's own `max_runs_per_hour` (default 60) and `max_concurrent` (default 3). A webhook's `signing_secret` is returned once, here. config:write. Off unless the deployment sets `HOSTED_AGENTS_ENABLED=true`.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The agent slug.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "webhook", "schedule", "plugin_event" ] }, "name": { "type": "string" }, "key_hash": { "type": "string" }, "plugin": { "type": "string", "description": "plugin_event: the installed plugin's slug." }, "event_type": { "type": "string", "description": "plugin_event: an event the plugin's manifest declares, e.g. order.created." }, "input_template": { "type": "string", "description": "At most 4000 characters." }, "every_minutes": { "type": "integer", "minimum": 5, "maximum": 10080 }, "event_id_field": { "type": "string", "description": "A field path, e.g. `id` or `data.event_id`." }, "max_runs_per_hour": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 60 }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 50, "default": 3 } }, "required": [ "kind", "name", "key_hash", "input_template" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AgentTrigger" }, { "type": "object", "properties": { "signing_secret": { "type": "string", "description": "Webhook only; shown once." } } } ] } }, "required": [ "data" ] } } } }, "400": { "description": "A field out of range, a field the kind cannot use, a key that is not an active inference key of this organisation, or `at most 20 triggers per agent`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/agents/triggers/{id}": { "patch": { "operationId": "setAgentTriggerStatus", "tags": [ "Agents" ], "summary": "Pause or resume a trigger", "description": "Only `status`; delete and recreate a trigger to change anything else. config:write.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The trigger id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "active", "paused" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentTrigger" } }, "required": [ "data" ] } } } }, "400": { "description": "Not a status, or another field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAgentTrigger", "tags": [ "Agents" ], "summary": "Delete a trigger", "description": "Its runs keep their record. config:write.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The trigger id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/agents/hooks/{id}": { "post": { "operationId": "deliverAgentWebhook", "tags": [ "Agents" ], "summary": "Deliver an event to a webhook trigger", "description": "Authenticated by `X-Autonomous-Relay-Signature: t=,v1=.\">` under the trigger's signing secret, valid for five minutes -- the form the gateway's own webhooks carry. The body must be a JSON object, at most 256 KB; it is rendered into the run's input and not stored. Answers 202 with the run's id at once; the run goes on in the background and is on the Runs page. An unknown, paused or badly signed delivery is the same 401.", "security": [ { "webhookSignature": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The trigger id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "duplicate": { "type": "boolean" }, "event_id": { "type": "string" } } } }, "required": [ "data" ] } } } }, "202": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "run_id": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unknown trigger, paused trigger, or a missing, stale or wrong signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Hosted agents are not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The agent is not active, or the trigger's key is revoked, expired or paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The trigger is at its max_runs_per_hour or max_concurrent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/agents/approvals": { "get": { "operationId": "listAgentApprovals", "tags": [ "Agents" ], "summary": "List hosted agents' pending actions", "description": "Actions hosted agents proposed and that wait for, or got, a person's decision. Names only; the arguments are on the action itself, for config:write. Newest first; at most 200. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`pending` (default), `approved`, `rejected` or `expired`.", "schema": { "enum": [ "pending", "approved", "rejected", "expired" ] } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PendingAction" } } }, "required": [ "data" ] } } } }, "400": { "description": "Not a status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/runs/{id}/actions/{action}": { "get": { "operationId": "getAgentAction", "tags": [ "Agents" ], "summary": "Get a pending action", "description": "`calls` holds the proposed calls with their arguments while the action is pending, and only for config:write; otherwise null. The arguments are erased when it is decided or expires.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run id.", "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "description": "The action id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PendingAction" }, { "type": "object", "properties": { "calls": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": [ "string", "null" ] } } } } } } ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "decideAgentAction", "tags": [ "Agents" ], "summary": "Approve or reject a pending action", "description": "Approving runs the proposed calls; rejecting tells the model they were refused (with your `note`, if any). Either way the run resumes and the conversation continues as the key that invoked the agent -- billed, capped and tagged as any of its turns -- and the answer is what `invoke` answers, with `decision`. The held state is erased in the same write that records the decision. config:write. Off unless the deployment sets `HOSTED_AGENTS_ENABLED=true`.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run id.", "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "description": "The action id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "enum": [ "approve", "reject" ] }, "note": { "type": "string", "description": "At most 500 characters. On a rejection, the model is told it." } }, "required": [ "decision" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentTurn" } }, "required": [ "data" ] } } } }, "202": { "description": "The continuation proposed another write: decide that one next.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentTurn" } }, "required": [ "data" ] } } } }, "400": { "description": "Not a decision, or a note out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The action was already decided, has expired (its run has ended), or its run is no longer waiting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/agents/{agent}/budgets/{interval}": { "put": { "operationId": "setAgentBudget", "tags": [ "Agents" ], "summary": "Set an agent budget", "description": "A hard ceiling on one agent's spend in a window, across every key it uses: a request naming the agent is refused with 403 `budget_exceeded` once the agent is at or past it. Narrower windows must have smaller caps. BYOK spend counts at list price by default.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The X-Autonomous-Relay-Agent value.", "schema": { "type": "string" } }, { "name": "interval", "in": "path", "required": true, "description": "`daily`, `weekly`, `monthly` or `lifetime`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit_usd": { "type": "number" }, "include_byok": { "type": "boolean", "default": true }, "mode": { "enum": [ "hard", "soft" ], "description": "`hard` refuses at the ceiling (403 `budget_exceeded`); `soft` serves, adds the sentence to `x-autonomous-relay-limit-warning`, and still alerts.", "default": "hard" }, "workspace_id": { "type": [ "string", "null" ], "description": "Scope the budget to this client workspace: it binds only requests from that workspace's keys. Omitted or null: the whole organisation. Both may exist for one agent and interval." } }, "required": [ "limit_usd" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "agent": { "type": "string" }, "interval": { "type": "string" }, "limit_usd": { "type": "number" }, "include_byok": { "type": "boolean" }, "mode": { "enum": [ "hard", "soft" ] }, "workspace_id": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] } } } }, "400": { "description": "A bad agent, interval or amount, or a budget above a wider window's.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "No such agent in this organisation." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAgentBudget", "tags": [ "Agents" ], "summary": "Remove an agent budget", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The X-Autonomous-Relay-Agent value.", "schema": { "type": "string" } }, { "name": "interval", "in": "path", "required": true, "description": "The window.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Remove the budget scoped to this client workspace. Absent: the organisation-wide one." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/alerts/channels": { "get": { "operationId": "listAlertChannels", "tags": [ "Alerts" ], "summary": "List usage-alert channels", "description": "Where the organisation is told that a key crossed a share of its spend ceiling. `email_available` says whether this deployment can send email. A webhook's signing secret is never returned here: only once, when the channel is created.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The channels.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertChannel" } }, "email_available": { "type": "boolean" } }, "required": [ "data", "email_available" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createAlertChannel", "tags": [ "Alerts" ], "summary": "Add a usage-alert channel", "description": "A key crossing any of `thresholds` (percent of its ceiling, default 50, 80 and 100), or an agent crossing them on one of its budgets (`agent_limit.threshold`), is announced once per threshold per ceiling window, on every channel that lists that threshold; a key that jumps several thresholds in one request is announced once, at the highest. A `webhook` target must be a public https URL on the default port; a `slack` target must be a `https://hooks.slack.com/...` incoming-webhook URL; `email` needs the deployment to be configured for it. Webhook deliveries are JSON, signed in `x-autonomous-relay-signature: t=,v1=`, where v1 is HMAC-SHA256 of `.` with the channel's `signing_secret`. At most 20 channels per organisation.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "webhook", "slack", "email" ] }, "target": { "type": "string", "description": "An https URL, or an email address for `email`." }, "name": { "type": "string" }, "thresholds": { "type": "array", "items": { "type": "integer" }, "description": "Whole percentages from 1 to 100. Default [50, 80, 100]." }, "events": { "type": "array", "items": { "enum": [ "usage", "price_drop" ] }, "description": "What the channel receives. `usage` (the default): key and agent limit crossings and runaway flags. `price_drop`: a model this organisation used in the last 30 days got cheaper (input or output tokens), announced once, within 15 minutes of the change." } }, "required": [ "kind", "target" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AlertChannel", "description": "The channel. For a webhook it also carries `signing_secret`, shown this once." } }, "required": [ "data" ] } } } }, "400": { "description": "An unsafe or malformed target, a Slack target that is not hooks.slack.com, email not configured, bad thresholds, or the 20-channel cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/alerts/channels/{id}": { "patch": { "operationId": "updateAlertChannel", "tags": [ "Alerts" ], "summary": "Change what a channel receives", "description": "Only `events`: a new target is a new channel. Changing events keeps the channel and its webhook signing secret. A `price_drop` event is JSON `{type, model, provider, sku, old_usd_per_million, new_usd_per_million, effective_at, at}`, with `x-autonomous-relay-event: price_drop`, signed as every other delivery is.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "enum": [ "usage", "price_drop" ] }, "description": "What the channel receives. `usage` (the default): key and agent limit crossings and runaway flags. `price_drop`: a model this organisation used in the last 30 days got cheaper (input or output tokens), announced once, within 15 minutes of the change." } }, "required": [ "events" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AlertChannel" } }, "required": [ "data" ] } } } }, "400": { "description": "`events must be a non-empty list of: usage, price_drop`, an unknown event, or a field other than `events`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAlertChannel", "tags": [ "Alerts" ], "summary": "Remove a usage-alert channel", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/alerts/channels/{id}/test": { "post": { "operationId": "testAlertChannel", "tags": [ "Alerts" ], "summary": "Send a test alert", "description": "Delivers a `test` event now and reports the outcome, so a wrong URL or a receiver that rejects the payload shows at once. The attempt is recorded in the delivery log.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "enum": [ "sent", "failed", "skipped" ] }, "http_status": { "type": [ "integer", "null" ], "description": "What the receiver answered, when it answered." }, "error": { "type": [ "string", "null" ], "description": "Why it failed, in our words. The receiver's response body is never read." } }, "required": [ "status" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/alerts/settings": { "get": { "operationId": "getAlertSettings", "tags": [ "Alerts" ], "summary": "What a runaway flag does", "description": "`alert`: every flag is sent to the alert channels and nothing else happens (the default). `pause`: a flagged KEY is also paused -- it answers 403 `key_paused` until resumed with PATCH /v1/keys/{hash} `{\"paused\": false}`. An agent flag is never a pause: a tag is not a credential.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "runaway_action": { "enum": [ "alert", "pause" ] } }, "required": [ "runaway_action" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "setAlertSettings", "tags": [ "Alerts" ], "summary": "Choose what a runaway flag does", "description": "Requires config:write (Developer or above): this decides whether a heuristic may stop production traffic.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runaway_action": { "enum": [ "alert", "pause" ] } }, "required": [ "runaway_action" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "runaway_action": { "enum": [ "alert", "pause" ] } }, "required": [ "runaway_action" ] } }, "required": [ "data" ] } } } }, "400": { "description": "A threshold out of range, named in the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/alerts/runaways": { "get": { "operationId": "listRunaways", "tags": [ "Alerts" ], "summary": "Runaway-spend flags", "description": "A key or an agent (X-Autonomous-Relay-Agent) flagged because its last 15 minutes were far above its own previous 24 hours: spend at least 3x its usual 15 minutes and at least $5, or requests at least 5x usual and at least 300. Checked every five minutes; a subject is flagged at most once an hour, and each flag is sent to every alert channel as a `spend.runaway` event. With `runaway_action` = `pause` (see /v1/alerts/settings) a flagged key is also paused; `action` says which happened. The last 30 days, at most 100.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "subject_kind": { "enum": [ "key", "agent" ] }, "subject": { "type": "string", "description": "The agent tag, or the first 12 characters of the key hash." }, "key_name": { "type": [ "string", "null" ] }, "key_hash": { "type": [ "string", "null" ], "description": "The full hash, for PATCH /v1/keys/{hash}; null for an agent." }, "key_paused": { "type": "boolean", "description": "Whether the key is paused right now (by this flag, a later one, or by hand)." }, "action": { "enum": [ "alert", "paused" ], "description": "What the sweep did with this flag." }, "kind": { "enum": [ "spend", "rate" ] }, "window_start": { "type": "string", "format": "date-time" }, "window_end": { "type": "string", "format": "date-time" }, "spend": { "type": "number", "description": "US dollars." }, "usual_spend": { "type": "number", "description": "US dollars." }, "requests": { "type": "integer" }, "usual_requests": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/alerts/deliveries": { "get": { "operationId": "listAlertDeliveries", "tags": [ "Alerts" ], "summary": "Recent alert deliveries", "description": "The last 50 delivery attempts, newest first, each with its outcome. Kept for 90 days.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertDelivery" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/byok": { "get": { "operationId": "listByokCredentials", "tags": [ "BYOK" ], "summary": "List provider credentials", "description": "Keys are never returned, by this or any route -- only `key_hint`.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ByokCredential" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createByokCredential", "tags": [ "BYOK" ], "summary": "Add a provider credential", "description": "Encrypted with a per-credential key before it is stored. Nothing routes until you have one for the provider that serves your model.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "description": "A provider slug with an adapter, e.g. `anthropic`." }, "api_key": { "type": "string", "writeOnly": true }, "name": { "type": "string" }, "tier": { "enum": [ "prioritized", "fallback" ] }, "priority": { "type": "integer" }, "fallback_policy": { "enum": [ "platform", "none_for_models", "none_for_provider" ] }, "model_filter": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } } }, "allowed_models": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string" }, "description": "Model ids or `*` patterns, ANDed with `model_filter`." }, "allowed_api_key_hashes": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "Only these API keys (their `hash`, as `GET /v1/keys` lists it) may use the credential." }, "allowed_user_ids": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string", "format": "uuid" }, "description": "Only keys these members are behind -- created, or signed in with -- may use the credential. A key no person is behind is outside the list." } }, "required": [ "provider", "api_key" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ByokCredential" } }, "required": [ "data" ] } } } }, "400": { "description": "`provider is required`, `api_key is required`, no adapter exists for the provider, or a scope field is malformed or names a key or person outside the organisation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "BYOK key management is not configured on this deployment (`service_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/byok/{id}": { "patch": { "operationId": "updateByokCredential", "tags": [ "BYOK" ], "summary": "Enable, disable or scope a provider credential", "description": "`disabled` and the three scope fields can change; a field left out is unchanged, `null` makes it unrestricted. To change the key, add a new credential and delete this one.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A credential `id`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean" }, "allowed_models": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string" }, "description": "Model ids or `*` patterns, ANDed with `model_filter`." }, "allowed_api_key_hashes": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "Only these API keys (their `hash`, as `GET /v1/keys` lists it) may use the credential." }, "allowed_user_ids": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string", "format": "uuid" }, "description": "Only keys these members are behind -- created, or signed in with -- may use the credential. A key no person is behind is outside the list." } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ByokCredential" } }, "required": [ "data" ] } } } }, "400": { "description": "Another field was patched, or a scope field is malformed or names a key or person outside the organisation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteByokCredential", "tags": [ "BYOK" ], "summary": "Delete a provider credential", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A credential `id`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/guardrails": { "get": { "operationId": "listGuardrails", "tags": [ "Guardrails" ], "summary": "List guardrails", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Guardrail" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createGuardrail", "tags": [ "Guardrails" ], "summary": "Create a guardrail", "description": "Assign it to a key to take effect. Policy merges organization, then workspace, then key, and each level can only narrow what the one above allows (§4.2).\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "limit_usd": { "type": "number", "description": "A budget in USD, evaluated per key." }, "reset_interval": { "enum": [ "daily", "weekly", "monthly", "lifetime" ] }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "allowed_providers": { "type": "array", "items": { "type": "string" } }, "allowed_data_regions": { "type": "array", "items": { "type": "string" }, "description": "Regions an endpoint may run in, matched exactly against the endpoint `deployment_region` field and lower-cased on write. Empty is unrestricted. This fails CLOSED: an endpoint that declares no region is not in one, so it is refused. A region no ready endpoint declares is rejected at write time rather than refusing every request later." }, "include_byok_in_budgets": { "type": "boolean", "description": "Count spend made on your own provider credential toward this ceiling, at IMPUTED LIST PRICE -- what the call would have cost on platform capacity, not the platform fee charged. Defaults to true: every model is BYOK-only, so a ceiling that skipped this spend would count nothing and could never bind. Set false to count only platform spend." }, "enforce_zdr": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Removed. An object of `false` is accepted; any `true` is a 400." }, "content_filter_builtins": { "type": "array", "items": { "enum": [ "email", "phone", "ssn", "credit-card", "ip-address", "secrets", "person-name", "address", "prompt-injection" ] } }, "content_filters": { "type": "array", "items": { "$ref": "#/components/schemas/ContentFilter" } }, "filter_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Phrases a filter must never act on." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "budget_nanodollars": { "type": [ "string", "null" ], "description": "Nanodollars (1e-9 USD), an integer as a string." }, "budget_reset": { "type": [ "string", "null" ] }, "content_filter_builtins": { "type": "array", "items": { "type": "string" } }, "content_filters": { "type": "array", "items": { "$ref": "#/components/schemas/ContentFilter" } }, "filter_allowlist": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "data" ] } } } }, "400": { "description": "`name is required`, or the filter policy is invalid; the message names the filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/guardrails/redaction": { "get": { "operationId": "getOrgRedaction", "tags": [ "Guardrails" ], "summary": "Get the organisation-wide PII redaction", "description": "The built-in detectors redacted from every request the organisation makes, on every plan. Any role may read this.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "builtins": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "builtins", "updated_at" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "setOrgRedaction", "tags": [ "Guardrails" ], "summary": "Set the organisation-wide PII redaction", "description": "Every plan, Solo included. Replaces the list; `[]` turns it off. Owner and Admin only (`org:write`). Built-in detectors only, and redact mode only: each match is replaced by its label (`[email]`, `[SECRET:openai-key]`) before routing, for every key in the organisation. It merges with the key's guardrails by union, so a guardrail can add detectors, custom patterns or block mode, never remove these. Custom patterns, block mode and per-workspace or per-key policies are guardrails (Team plan): asking for them here is a 402 `subscription_required` on Solo and a 400 on Team.\n\nNeeds the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "builtins": { "type": "array", "items": { "enum": [ "email", "phone", "ssn", "credit-card", "ip-address", "secrets", "prompt-injection" ] } }, "action": { "enum": [ "redact" ], "description": "Optional; redaction is the only action at this level." } }, "required": [ "builtins" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "builtins": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "builtins", "updated_at" ] } }, "required": [ "data" ] } } } }, "400": { "description": "An unknown detector or field, or (on Team) a guardrail-only field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Solo: a custom pattern, block mode or a per-workspace or per-key scope (`subscription_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/guardrails/{id}": { "delete": { "operationId": "deleteGuardrail", "tags": [ "Guardrails" ], "summary": "Delete a guardrail", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A guardrail `id`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/guardrails/{id}/assign": { "post": { "operationId": "assignGuardrail", "tags": [ "Guardrails" ], "summary": "Assign a guardrail", "description": "Needs the Pro ($29/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A guardrail `id`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_type": { "enum": [ "key", "member" ] }, "subject_id": { "type": "string", "description": "For a key, its `hash`." } }, "required": [ "subject_type", "subject_id" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "guardrail_id": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "`subject_type and subject_id are required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/workspaces": { "get": { "operationId": "listWorkspaces", "tags": [ "Workspaces" ], "summary": "List workspaces", "description": "One workspace per client is the intended use: each has its own keys, budgets and spend, under one account and one balance. `spend_this_month` is measured the way a workspace budget is -- settled spend in the current UTC calendar month plus requests in flight, BYOK spend at list price included.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createWorkspace", "tags": [ "Workspaces" ], "summary": "Create a workspace", "description": "At most 200 per organisation. Put keys in it with `workspace_id` on `POST /v1/keys`, or move one with `PATCH /v1/keys/{hash}`.\n\nNeeds the Team ($99/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Up to 80 characters, e.g. the client's name." }, "description": { "type": "string", "description": "Optional, up to 500 characters." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } } }, "400": { "description": "`name is required`, too long, or the 200-workspace cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/workspaces/{id}": { "patch": { "operationId": "renameWorkspace", "tags": [ "Workspaces" ], "summary": "Rename or describe a workspace", "description": "Send `name`, `description` (null clears it) or both. A seat limited to workspaces needs to be an admin of this one.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The workspace id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteWorkspace", "tags": [ "Workspaces" ], "summary": "Remove a workspace", "description": "Refused with 409 while the workspace has an active key, and for the organisation's last workspace. Revoked keys keep their history and lose the link; provider credentials are never removed with a workspace.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The workspace id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The workspace has active keys, or it is the last one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/workspaces/{id}/budgets": { "get": { "operationId": "listWorkspaceBudgets", "tags": [ "Workspaces" ], "summary": "List a workspace's budgets", "description": "An unknown workspace is an empty list, not a 404.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A workspace id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceBudget" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/workspaces/{id}/budgets/{interval}": { "put": { "operationId": "setWorkspaceBudget", "tags": [ "Workspaces" ], "summary": "Set a workspace budget", "description": "Budgets must shrink as the interval narrows: a daily budget above the weekly one is refused. Each interval is its own ceiling; they are never summed.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A workspace id.", "schema": { "type": "string" } }, { "name": "interval", "in": "path", "required": true, "description": "The budget's period.", "schema": { "enum": [ "daily", "weekly", "monthly", "lifetime" ] } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit_usd": { "type": "number", "minimum": 0 }, "include_byok": { "type": "boolean" } }, "required": [ "limit_usd" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "interval": { "type": "string" }, "limit_usd": { "type": "number", "description": "US dollars." } } } }, "required": [ "data" ] } } } }, "400": { "description": "An unknown interval, a negative limit, or a budget larger than a longer interval's.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Workspace not found." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteWorkspaceBudget", "tags": [ "Workspaces" ], "summary": "Delete a workspace budget", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A workspace id.", "schema": { "type": "string" } }, { "name": "interval", "in": "path", "required": true, "description": "The budget's period.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deleted" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Budget not found." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/workspaces/{id}/members": { "get": { "operationId": "listWorkspaceMembers", "tags": [ "Workspaces" ], "summary": "List a workspace's members", "description": "The people given a role in this workspace. Membership matters only to seats limited to workspaces (`scope: \"workspaces\"` on `PATCH /v1/members/{userId}`): everyone else sees every workspace.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The workspace id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "role": { "enum": [ "admin", "member" ] }, "created_at": { "type": "string", "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "org_role": { "enum": [ "owner", "admin", "member", "billing", "readonly" ], "description": "owner = Owner, member = Developer, billing = Finance. What each may do: see the Members tag." }, "scope": { "enum": [ "org", "workspaces" ], "description": "`workspaces`: limited to the workspaces this person is a member of." } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Workspace not found." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/workspaces/{id}/members/{userId}": { "put": { "operationId": "setWorkspaceMember", "tags": [ "Workspaces" ], "summary": "Add a workspace member or change their role", "description": "A workspace `admin` can rename it, set its budgets and manage its members; a `member` can use it (keys, logs, reports). Allowed for an owner or admin of the organisation, or an admin of this workspace. The person must have an active seat.\n\nNeeds the Team ($99/month) plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The workspace id.", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "The member's user id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "enum": [ "admin", "member" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "user_id": { "type": "string" }, "role": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "An unknown role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "$ref": "#/components/responses/PlanRequired" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Workspace or member not found." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "removeWorkspaceMember", "tags": [ "Workspaces" ], "summary": "Remove a workspace member", "description": "A seat limited to workspaces loses this one at once; with none left, it sees nothing.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The workspace id.", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "The member's user id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "removed": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Not a member of this workspace." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/runs": { "post": { "operationId": "openRun", "tags": [ "Runs" ], "summary": "Open a run", "description": "A run is one goal across many turns, with **one budget enforced across all of them**. Pass its `id` as `run_id` on each completion.\n\nInference class, not management: the thing that opens a run is the agent, and requiring a management key would hand every agent the credential that mints keys and moves budgets. The run is scoped to the organization, so a supervisor and its workers may hold different keys and share one.", "security": [ { "inferenceKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "type": "string", "description": "Free text, at most 2000 characters." }, "budget_usd": { "type": "number", "description": "**Required**, and positive. There is no way to open an uncapped run." }, "max_turns": { "type": "integer", "minimum": 1, "description": "Bounds how many times the agent may ask. A failed turn refunds its money but **not** its turn — see `packages/docs/RUNS.md`." }, "max_tool_calls": { "type": "integer", "minimum": 1, "description": "Checked at turn admission, so a single turn can exceed it by its own call count." }, "model_policy": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string", "description": "An empty or absent list means unrestricted, never deny-all." } }, "deny": { "type": "array", "items": { "type": "string", "description": "Wins over `allow`." } } } }, "max_cost_per_minute_usd": { "type": "number", "exclusiveMinimum": 0, "description": "§17.4 runaway detector, **opt-in**. Pauses the run when spend inside a tumbling one-minute window exceeds this. Omit to leave it off.\n\nThe window is tumbling, not sliding: a burst straddling a boundary can be split across two windows and escape. Acceptable for a safety net whose job is to stop a loop running overnight; it is not a billing control." }, "max_tool_calls_without_progress": { "type": "integer", "minimum": 1, "description": "§17.4 runaway detector, **opt-in**. Pauses the run after this many consecutive tool calls with no answering turn between them — \"progress\" meaning a turn that finished with something other than `tool_calls`. Omit to leave it off." } }, "required": [ "budget_usd" ] } } } }, "responses": { "201": { "description": "Opened.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Run" } }, "required": [ "data" ] } } } }, "400": { "description": "`budget_usd is required and must be a positive number`, or a malformed cap or `model_policy`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "listRuns", "tags": [ "Runs" ], "summary": "List runs", "description": "Newest first, for the calling key's organization. An inference key, or a management key or dashboard session whose role grants `usage:read`.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "required": false, "description": "One status only.", "schema": { "enum": [ "open", "paused", "completed", "exhausted", "cancelled" ] } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } }, "required": [ "data" ] } } } }, "400": { "description": "`status must be one of: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/runs/{id}": { "get": { "operationId": "getRun", "tags": [ "Runs" ], "summary": "Get a run and its tree", "description": "§17.1's tree: turns, per-turn cost, cache hit rate, failed tool calls, model switches and a terminal status. An inference key, or a management key or dashboard session whose role grants `usage:read`.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RunTree" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/runs/{id}/close": { "post": { "operationId": "closeRun", "tags": [ "Runs" ], "summary": "Close a run", "description": "Terminal. An `open` or `paused` run closes; closing an already-closed run is a 409 naming its current status, never a silent no-op. An inference key, or a management key or dashboard session whose role grants `config:write`.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run id.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "completed", "cancelled" ], "default": "completed" } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Run" } }, "required": [ "data" ] } } } }, "400": { "description": "`status must be one of: completed, cancelled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The run is already `completed`, `cancelled` or `exhausted`. The body reports `code: 400` and `invalid_request`, although the status is 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/runs/{id}/resume": { "post": { "operationId": "resumeRun", "tags": [ "Runs" ], "summary": "Resume a run the runaway detector paused", "description": "The counterpart to pausing rather than cancelling (§17.4): the detector stops a run so a human can look at it, and this is how they say \"I looked, carry on\".\n\nClears the counters that caused the pause — without that it would pause again on the very next settlement and this call would appear to do nothing. The budget and turn counts are deliberately **not** reset: those are the caps the run was opened under, and a pause is not an amnesty.\n\nOnly a `paused` run resumes. `exhausted` and `cancelled` are genuinely finished, and resuming those would be a way to reopen a budget that has already bound.\n\nAn inference key, or a management key or dashboard session whose role grants `config:write`.", "security": [ { "inferenceKey": [] }, { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Run" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The run is not paused. The body reports `code: 400` and `invalid_request`, although the status is 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mcp": { "post": { "operationId": "callMcp", "tags": [ "MCP" ], "summary": "Call the MCP server", "description": "JSON-RPC 2.0 over MCP's Streamable HTTP transport, protocol revision `2025-06-18`. Methods: `initialize`, `tools/list`, `tools/call`, `ping`, and the `notifications/*` messages.\n\nEvery tool is an adapter over a route documented elsewhere in this file, dispatched through this gateway's own router — so an MCP call passes the same authentication, rate limits, spend ceilings, guardrails and ledger as the HTTP call it stands for. See `packages/docs/MCP.md`.\n\nRequires an **inference** key; a management key gets 403, as it does on `/v1/chat/completions`. The OAuth PKCE flow (`/auth`) is the intended way for a coding tool to obtain one.\n\nStateless: no `Mcp-Session-Id`, because several instances run behind a load balancer with no sticky routing. JSON-RPC **batching is refused** — revision `2025-06-18` removed it.", "security": [ { "inferenceKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ], "description": "Omit the field entirely for a notification, which is answered with 202 and no body. An explicit `null` is a request, not a notification." }, "method": { "type": "string", "description": "e.g. `tools/call`." }, "params": { "type": "object", "additionalProperties": true } }, "required": [ "jsonrpc", "method" ] } } } }, "responses": { "200": { "description": "A JSON-RPC response. A TOOL that failed returns a success envelope with `result.isError: true`; `error` is reserved for protocol faults — a malformed request, an unknown method, an unknown tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "result": { "type": "object", "additionalProperties": true, "description": "For `tools/call`: `content` (an array of text blocks) and `isError`." }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "jsonrpc", "id" ] } } } }, "202": { "description": "A notification was accepted. No body, by design: a client must not try to correlate a response to a request it never made." }, "401": { "$ref": "#/components/responses/InferenceUnauthorized" }, "403": { "$ref": "#/components/responses/InferenceForbidden" }, "429": { "description": "`MCP rate limit exceeded`. Every POST counts against a per-key MCP quota of 300 a minute and 50,000 a day, separate from the inference quota that a `tools/call` also meets inside the route it calls. The `X-RateLimit-*` headers are on every response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getMcpStream", "tags": [ "MCP" ], "summary": "Not offered: this server has no server-initiated stream", "description": "Always 405. MCP's transport requires that status from a server offering no SSE stream, and it is answered deliberately rather than left to a 404, because a client probing for a stream must read \"not offered\" rather than \"wrong URL\".", "security": [], "x-auth": "public", "responses": { "405": { "description": "`This MCP server offers no server-initiated stream; use POST.` The body reports `code: 400` and `invalid_request`, although the status is 405.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mcp/server-card": { "get": { "operationId": "getMcpServerCard", "tags": [ "MCP" ], "summary": "The MCP Server Card", "description": "This MCP server's Server Card (SEP-2127), for discovery before connecting: its identity, the Streamable HTTP endpoint, the protocol revisions it speaks, and the `Authorization` header it needs. It lists no tools; `tools/list` does, at runtime. Served as `application/mcp-server-card+json`, readable from any origin, cacheable for an hour, and listed in the site's agent catalogue (`/.well-known/ard.json`).", "security": [], "x-auth": "public", "responses": { "200": { "description": "The card. Its schema is `https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json`.", "content": { "application/mcp-server-card+json": { "schema": { "type": "object", "properties": { "$schema": { "type": "string" }, "name": { "type": "string", "description": "Reverse-DNS: `com.autonomousrelay/agentsrouter`." }, "version": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "websiteUrl": { "type": "string" }, "icons": { "type": "array", "items": { "type": "object" } }, "remotes": { "type": "array", "items": { "type": "object", "description": "One `streamable-http` endpoint, with its protocol revisions and the `Authorization` header." } } }, "required": [ "$schema", "name", "version", "description" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/session": { "post": { "operationId": "createSession", "tags": [ "Auth" ], "summary": "Exchange a management key for a dashboard session", "description": "Sets the httpOnly `ar_session` cookie and the script-readable `ar_csrf` cookie. Rate limited per client address.", "security": [], "x-auth": "A management key, in the body as `key`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "writeOnly": true, "description": "A management key." } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Session" } }, "required": [ "data" ] } } } }, "400": { "description": "`key is required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`Invalid credentials` -- for any failure, a wrong key class included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getSession", "tags": [ "Auth" ], "summary": "Get the current session", "security": [ { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Session" } }, "required": [ "data" ] } } } }, "401": { "description": "No session, or it is invalid or has expired. An invalid one also clears the cookies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "endSession", "tags": [ "Auth" ], "summary": "Sign out", "description": "Always succeeds, and clears both cookies.", "security": [ { "session": [] }, {} ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ended": { "const": true } }, "required": [ "ended" ] } }, "required": [ "data" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/authorize": { "get": { "operationId": "describeAuthorization", "tags": [ "Auth" ], "summary": "Describe an OAuth PKCE authorization request", "description": "What the consent screen at `/auth` renders. Public and rate limited: it validates the query string and echoes back the terms a key issued under it would carry. It reads nothing about any account, so a malformed request is refused before the user is asked to sign in.", "security": [], "x-auth": "public", "parameters": [ { "name": "callback_url", "in": "query", "required": false, "description": "Where to return the code. Omit for the headless flow, which then requires `S256` and `key_label`. `https` only, except on localhost.", "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "required": false, "description": "The PKCE challenge, 43-128 characters.", "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": false, "description": "Must be `S256`, sent explicitly. `plain` and `none` are refused for every flow, redirect included: a code returned to a localhost callback can be read by any process on that machine, and only a hashed challenge keeps it from minting a key there (RFC 7636 §7.2).", "schema": { "enum": [ "S256" ] } }, { "name": "key_label", "in": "query", "required": false, "description": "Names the issued key on the Keys screen. Defaults to the callback host.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthorizeInfo" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "An invalid `code_challenge_method`, a challenge of the wrong length, or a headless request missing `S256` or `key_label`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "The callback URL is not `https` (and is not localhost), or uses a scheme other than http/https. s16.2 specifies 405 here rather than 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "grantAuthorization", "tags": [ "Auth" ], "summary": "Approve an app and mint a one-time code", "description": "Called by the consent screen once the user agrees. The request is re-validated from the body: the preceding `GET` is a convenience and proves nothing about this call. Codes are single-use and expire in ten minutes.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback_url": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "enum": [ "S256", "plain", "none" ] }, "key_label": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthGrant" } }, "required": [ "data" ] } } } }, "400": { "description": "As for the `GET`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "405": { "description": "As for the `GET`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/keys": { "post": { "operationId": "exchangeAuthorizationCode", "tags": [ "Auth" ], "summary": "Exchange a PKCE code for an API key", "description": "Unauthenticated by design -- the caller is an app that has no key yet, and the code plus its verifier are the credential. This is the one route that answers cross-origin (`Access-Control-Allow-Origin: *`), because a single-page app is exactly the public client PKCE exists for. `Access-Control-Allow-Credentials` is never set, so no cookie can ride along.\n\nThe code is consumed the moment it is looked up, **including when verification then fails**: a caller gets one attempt at the verifier, not a grinding window (RFC 6749 §4.1.2). The issued key is an inference key carrying a spend ceiling and an expiry, and is revocable from the Keys screen like any other.", "security": [], "x-auth": "The one-time authorization code and its PKCE verifier, in the body.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "The code from the callback, or pasted from the headless flow." }, "code_verifier": { "type": "string", "description": "The PKCE verifier. Required unless the code was issued under `none`." }, "code_challenge_method": { "enum": [ "S256", "plain", "none" ], "description": "Optional. If sent it must MATCH the method the code was issued under; it never replaces it." } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthKey" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "`code is required`, or a `code_challenge_method` that disagrees with the stored one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`code is invalid, already used, or expired` -- one message for all three, so a guess cannot confirm that a code exists -- or `code_verifier does not match the code_challenge`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/oauth/token": { "post": { "operationId": "federationTokenExchange", "tags": [ "Federation" ], "summary": "Exchange a workload identity token for an inference token", "description": "RFC 8693 token exchange (§16.3). Public: the subject token is the credential. Send the identity token your platform gives the workload -- a GitHub Actions OIDC token, a cloud workload identity, a Kubernetes service-account token -- with the id of the federation policy it should match. The token must be signed RS256 or ES256 by the policy's issuer (checked against the issuer's published keys), unexpired, with `iss`, `sub` and `aud` exactly the policy's and every claim check holding. The answer is a Bearer token scoped `inference`, valid for at most 900 seconds and never past the subject token's own `exp`, accepted wherever an inference key is and acting as the key the policy names: its limit, workspace, IP allowlist and pause apply, and revoking the key ends the token. Form-encoded or JSON; body at most 32 KB, subject token at most 16 KB. Errors are RFC 6749 bodies (`error`, `error_description`).", "security": [], "x-auth": "The workload's signed identity token, in the body as `subject_token`, checked against the federation policy.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "enum": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "subject_token_type": { "enum": [ "urn:ietf:params:oauth:token-type:jwt", "urn:ietf:params:oauth:token-type:id_token" ] }, "subject_token": { "type": "string", "description": "The workload's signed identity token (a JWS)." }, "federation_policy_id": { "type": "string", "description": "The policy to exchange under." } }, "required": [ "grant_type", "subject_token_type", "subject_token", "federation_policy_id" ] } } } }, "responses": { "200": { "description": "The access token. `Cache-Control: no-store`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "issued_token_type": { "enum": [ "urn:ietf:params:oauth:token-type:access_token" ] }, "token_type": { "enum": [ "Bearer" ] }, "expires_in": { "type": "integer" }, "scope": { "enum": [ "inference" ] } }, "required": [ "access_token", "issued_token_type", "token_type", "expires_in", "scope" ] } } } }, "400": { "description": "`unsupported_grant_type`, `invalid_request`, or `invalid_grant` with what failed: no active policy with that id, the key it acts as is not active, or which check the subject token failed." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "`temporarily_unavailable`: federation is not enabled on this deployment." } } } }, "/v1/oauth/jwks": { "get": { "operationId": "federationJwks", "tags": [ "Federation" ], "summary": "The keys our access tokens are signed with", "description": "Public. A JWK Set of ES256 public keys: the current signing key and, during a rotation, the previous one. Empty when federation is not enabled. Cacheable for five minutes.", "security": [], "x-auth": "public", "responses": { "200": { "description": "A JWK Set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "keys" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/federation/policies": { "get": { "operationId": "listFederationPolicies", "tags": [ "Federation" ], "summary": "List federation policies", "description": "Owner or Admin. `enabled` says whether this deployment can issue tokens at all.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The policies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "issuer_url": { "type": "string" }, "subject": { "type": "string" }, "audience": { "type": "string" }, "acts_as_key_hash": { "type": "string", "description": "The inference key an exchanged token acts as." }, "claim_checks": { "type": "object", "additionalProperties": true }, "status": { "enum": [ "active", "paused" ] }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "issuer_url", "subject", "audience", "acts_as_key_hash", "claim_checks", "status" ] } }, "enabled": { "type": "boolean" } }, "required": [ "data", "enabled" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createFederationPolicy", "tags": [ "Federation" ], "summary": "Create a federation policy", "description": "Which workload tokens are accepted (`issuer_url`, `subject`, `audience`, `claim_checks`) and the inference key the exchanged token acts as (`acts_as_key_hash`, an active inference key of this organisation). The issuer must be a public https URL serving an OIDC discovery document with a `jwks_uri`. `claim_checks`: up to 20 `{\"claim\": expected}`; a string, number or boolean claim must equal it, an array claim must contain it. Owner or Admin.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "issuer_url": { "type": "string" }, "subject": { "type": "string" }, "audience": { "type": "string" }, "acts_as_key_hash": { "type": "string" }, "claim_checks": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "name", "issuer_url", "subject", "audience", "acts_as_key_hash" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "issuer_url": { "type": "string" }, "subject": { "type": "string" }, "audience": { "type": "string" }, "acts_as_key_hash": { "type": "string", "description": "The inference key an exchanged token acts as." }, "claim_checks": { "type": "object", "additionalProperties": true }, "status": { "enum": [ "active", "paused" ] }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "issuer_url", "subject", "audience", "acts_as_key_hash", "claim_checks", "status" ] } }, "required": [ "data" ] } } } }, "400": { "description": "A missing or malformed field, an issuer that is not a public https URL, or a key that is not an active inference key of this organisation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/federation/policies/{id}": { "patch": { "operationId": "updateFederationPolicy", "tags": [ "Federation" ], "summary": "Change or pause a federation policy", "description": "Any of `name`, `issuer_url`, `subject`, `audience`, `claim_checks`, and `status` (`active` or `paused`). Pausing stops new exchanges at once; tokens already issued run out their clock (at most 900 seconds). Owner or Admin.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The policy id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "issuer_url": { "type": "string" }, "subject": { "type": "string" }, "audience": { "type": "string" }, "claim_checks": { "type": "object", "additionalProperties": true }, "status": { "enum": [ "active", "paused" ] } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "issuer_url": { "type": "string" }, "subject": { "type": "string" }, "audience": { "type": "string" }, "acts_as_key_hash": { "type": "string", "description": "The inference key an exchanged token acts as." }, "claim_checks": { "type": "object", "additionalProperties": true }, "status": { "enum": [ "active", "paused" ] }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "issuer_url", "subject", "audience", "acts_as_key_hash", "claim_checks", "status" ] } }, "required": [ "data" ] } } } }, "400": { "description": "A malformed field, or nothing to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteFederationPolicy", "tags": [ "Federation" ], "summary": "Delete a federation policy", "description": "Stops new exchanges at once; tokens already issued run out their clock (at most 900 seconds). To end those too, revoke the key the policy acts as. Owner or Admin.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The policy id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sso": { "get": { "operationId": "getSso", "tags": [ "SSO" ], "summary": "The single sign-on setup", "description": "The connection to your identity provider, your email domains with the TXT record each needs, and the callback URL to register. Owner or Admin.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putSso", "tags": [ "SSO" ], "summary": "Connect your identity provider", "description": "Your OIDC app's issuer, client id and client secret. The issuer's discovery document (`/.well-known/openid-configuration`) is read now and must name the same issuer. A new connection, or a changed issuer or client id, is `pending` (with `require_sso` off) until a test sign-in succeeds and it is activated again; a new secret alone keeps the connection as it is. The secret is sealed and never returned; omit it to keep the stored one. Business plan or above; Owner or Admin.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } }, "required": [ "issuer", "client_id" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "400": { "description": "A missing field, or an issuer whose discovery document cannot be read or names another issuer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Not on the Business or Enterprise plan (`subscription_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchSso", "tags": [ "SSO" ], "summary": "Require single sign-on", "description": "With `require_sso: true`, people at your verified domains can only sign in through your identity provider; Google, GitHub and wallet sign-in and switching in from another organisation are refused for them (403 `sso_required`). Your Owners are exempt and keep their original method, so an identity-provider outage cannot lock you out. Turning it on ends the current dashboard sessions of the people it applies to. Needs an active connection.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "require_sso": { "type": "boolean" } }, "required": [ "require_sso" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Not on the Business or Enterprise plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The connection is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteSso", "tags": [ "SSO" ], "summary": "Remove the connection", "description": "Your verified domains are kept. Not plan-gated.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sso/saml": { "put": { "operationId": "putSsoSaml", "tags": [ "SSO" ], "summary": "Connect a SAML identity provider", "description": "Either `metadata_xml` (the IdP metadata file exported from Okta, Entra, Google Workspace, ADFS...) or `entity_id`, `sso_url` (HTTP-Redirect binding, https) and `certificate` (the signing certificate, PEM or base64). Replaces an OIDC connection. A new identity provider is `pending` (with `require_sso` off) until a test sign-in passes and it is activated again; a renewed certificate keeps the connection as it is. Assertions must be signed. Business plan or above; Owner or Admin.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata_xml": { "type": "string" }, "entity_id": { "type": "string" }, "sso_url": { "type": "string" }, "certificate": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "400": { "description": "Not identity provider metadata, no HTTP-Redirect sign-on URL, an http URL, or no signing certificate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Not on the Business or Enterprise plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/sso/saml/metadata": { "get": { "operationId": "samlSpMetadata", "tags": [ "Auth" ], "summary": "Our SAML service provider metadata", "description": "Public. Import it into your identity provider, or copy the entity ID and ACS URL from it.", "security": [], "x-auth": "public", "responses": { "200": { "description": "SAML 2.0 metadata.", "content": { "application/samlmetadata+xml": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/sso/saml/acs": { "post": { "operationId": "samlAcs", "tags": [ "Auth" ], "summary": "SAML Assertion Consumer Service", "description": "Where your identity provider posts the SAMLResponse (HTTP-POST binding, form-encoded) with the RelayState. The Assertion must be signed by a certificate from your metadata, issued by your entity ID, for our entity ID, within its validity window, and answer the AuthnRequest this browser started (once; the `ar_saml` cookie must match the RelayState). Then as the OIDC callback: the email must be at a verified domain, and a first sign-in creates a Developer seat limited to workspaces.", "security": [], "x-auth": "The SAML Assertion, signed by a certificate from the organisation's IdP metadata.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "SAMLResponse": { "type": "string" }, "RelayState": { "type": "string" } }, "required": [ "SAMLResponse", "RelayState" ] } } } }, "responses": { "302": { "description": "Signed in, to `/workspace`; or to the sign-in page with an error; a test sign-in returns to Settings.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sso/activate": { "post": { "operationId": "activateSso", "tags": [ "SSO" ], "summary": "Activate single sign-on", "description": "Needs a successful test sign-in (`GET /v1/auth/sso/test`) since the connection was last changed, and at least one verified domain. Business plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Not on the Business or Enterprise plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "No successful test sign-in yet, or no verified domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sso/disable": { "post": { "operationId": "disableSso", "tags": [ "SSO" ], "summary": "Turn single sign-on off", "description": "Sign-in through your identity provider stops at once, and `require_sso` is turned off. Not plan-gated.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sso/domains": { "post": { "operationId": "addSsoDomain", "tags": [ "SSO" ], "summary": "Add an email domain", "description": "Returns the TXT record to add at the domain's root (`autonomousrelay-verification=`). At most 20 domains. Business plan or above.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Such as acme.com." } }, "required": [ "domain" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "400": { "description": "Not a domain name, or the 20-domain cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Not on the Business or Enterprise plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sso/domains/{domain}/verify": { "post": { "operationId": "verifySsoDomain", "tags": [ "SSO" ], "summary": "Verify an email domain", "description": "Looks the TXT record up now. DNS changes can take up to an hour to be visible. A domain is verified by at most one organisation.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Not on the Business or Enterprise plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The record is not visible yet, or another organisation already verified this domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sso/domains/{domain}": { "delete": { "operationId": "deleteSsoDomain", "tags": [ "SSO" ], "summary": "Remove an email domain", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Register this exact URL as the redirect (sign-in) URI of your OIDC app." }, "saml_sp": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Our SAML entity ID (also the metadata URL)." }, "acs_url": { "type": "string", "description": "The Assertion Consumer Service URL (HTTP-POST)." }, "metadata_url": { "type": "string" } } }, "connection": { "type": [ "object", "null" ], "description": "`{ protocol: oidc|saml, status: pending|active|disabled, require_sso, tested_at, created_at, issuer, client_id, saml_entity_id, saml_sso_url }`; the client secret is never returned." }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "txt_record": { "type": "object", "properties": { "type": { "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/sso/discover": { "post": { "operationId": "discoverSso", "tags": [ "Auth" ], "summary": "Does this email sign in with SSO?", "description": "Public and rate-limited. True when the address's domain is verified by an organisation with an active connection.", "security": [], "x-auth": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sso": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Not an email address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/sso/start": { "get": { "operationId": "startSso", "tags": [ "Auth" ], "summary": "Start signing in with SSO", "description": "A browser navigation: redirects to your identity provider with PKCE, a nonce and a state cookie (`ar_sso`, ten minutes).", "security": [], "x-auth": "public", "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The work email; its domain picks the connection." } ], "responses": { "302": { "description": "To the identity provider, or back to `/signin?error=sso_unknown`.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/sso/test": { "get": { "operationId": "testSso", "tags": [ "SSO" ], "summary": "Run a test sign-in", "description": "A browser navigation from a signed-in Owner or Admin: a sign-in through your own connection, even while it is pending. It records the success (which `POST /v1/sso/activate` needs) and signs nobody in; the result comes back to `/workspace/settings?sso_test=ok|...`.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "302": { "description": "To the identity provider, or back to Settings with the reason it could not start.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/sso/callback": { "get": { "operationId": "ssoCallback", "tags": [ "Auth" ], "summary": "SSO callback", "description": "Where your identity provider sends the browser back. The ID token's issuer, audience, expiry and nonce are checked, and the email must be at one of your verified domains. A first sign-in creates a Developer seat limited to workspaces. Errors redirect to `/signin?error=` `sso_failed`, `sso_domain`, `seat_removed`, `state_mismatch`, `expired`, `cancelled` or `sso_unknown`.", "security": [], "x-auth": "The `state` matched to the flow cookie, and an ID token from the organisation's identity provider.", "responses": { "302": { "description": "Signed in, to `/workspace`; or to the sign-in page with an error; a test sign-in returns to `/workspace/settings?sso_test=`.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim/v2/ServiceProviderConfig": { "get": { "operationId": "scimServiceProviderConfig", "tags": [ "SCIM" ], "summary": "SCIM service provider configuration", "description": "PATCH and `eq` filters are supported; bulk, sort and etags are not.", "security": [ { "scimToken": [] } ], "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim/v2/ResourceTypes": { "get": { "operationId": "scimResourceTypes", "tags": [ "SCIM" ], "summary": "SCIM resource types", "description": "User and Group.", "security": [ { "scimToken": [] } ], "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim/v2/Users": { "get": { "operationId": "scimListUsers", "tags": [ "SCIM" ], "summary": "List provisioned users", "description": "Filter with `userName eq \"...\"` or `externalId eq \"...\"`; `startIndex` and `count` (at most 200) page.", "security": [ { "scimToken": [] } ], "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "scimCreateUser", "tags": [ "SCIM" ], "summary": "Provision a user", "description": "`userName` must be a work email at one of the organisation's verified SSO domains. A new seat is a Developer limited to workspaces; an existing account at that address is reused.", "security": [ { "scimToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim/v2/Users/{id}": { "get": { "operationId": "scimGetUser", "tags": [ "SCIM" ], "summary": "Get a provisioned user", "description": "One user.", "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "scimReplaceUser", "tags": [ "SCIM" ], "summary": "Replace a user", "description": "`active: false` deactivates the seat.", "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "scimPatchUser", "tags": [ "SCIM" ], "summary": "Update a user", "description": "PatchOp. `active` false (or \"False\") deactivates the seat: it ends, the person's dashboard sessions end, and API keys they created keep working and are flagged on `GET /v1/keys` (`creator_deactivated`). `active: true` does not reactivate a deactivated seat; an owner re-invites.", "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "scimDeleteUser", "tags": [ "SCIM" ], "summary": "Deprovision a user", "description": "The seat is deactivated as for `active: false`, and the person leaves every directory group.", "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done." }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim/v2/Groups": { "get": { "operationId": "scimListGroups", "tags": [ "SCIM" ], "summary": "List directory groups", "description": "Filter with `displayName eq \"...\"`; `excludedAttributes=members` omits the members.", "security": [ { "scimToken": [] } ], "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "scimCreateGroup", "tags": [ "SCIM" ], "summary": "Create a directory group", "description": "Only provisioned users can be members.", "security": [ { "scimToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim/v2/Groups/{id}": { "get": { "operationId": "scimGetGroup", "tags": [ "SCIM" ], "summary": "Get a directory group", "description": "One group and its members.", "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "scimReplaceGroup", "tags": [ "SCIM" ], "summary": "Replace a directory group", "description": "Its name and its whole member list.", "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "scimPatchGroup", "tags": [ "SCIM" ], "summary": "Update a directory group", "description": "add / remove / replace members (also `members[value eq \"id\"]`), or replace displayName. Workspace roles follow at once.", "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "scimDeleteGroup", "tags": [ "SCIM" ], "summary": "Delete a directory group", "description": "Its members lose the workspace roles it gave them.", "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done." }, "400": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "401": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "403": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "404": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "409": { "description": "A SCIM resource or error (application/scim+json).", "content": { "application/scim+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim": { "get": { "operationId": "getScim", "tags": [ "SCIM" ], "summary": "Directory sync settings", "description": "The SCIM base URL, the token (prefix and dates only), how many people are provisioned, and each directory group with its workspace mappings. Owner.", "security": [ { "managementKey": [] }, { "session": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "base_url": { "type": "string", "description": "The SCIM base URL to give your directory." }, "token": { "type": [ "object", "null" ], "description": "`{ prefix, created_at, last_used_at }`; the token itself is shown once, as `token_value` when created." }, "users": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "members": { "type": "integer" }, "mappings": { "type": "array", "items": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "workspace_name": { "type": "string" }, "role": { "enum": [ "admin", "member" ] } } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim/token": { "post": { "operationId": "mintScimToken", "tags": [ "SCIM" ], "summary": "Create or rotate the SCIM token", "description": "Returns `token_value` once; it replaces any previous token at once. Business plan or above; Owner.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "base_url": { "type": "string", "description": "The SCIM base URL to give your directory." }, "token": { "type": [ "object", "null" ], "description": "`{ prefix, created_at, last_used_at }`; the token itself is shown once, as `token_value` when created." }, "users": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "members": { "type": "integer" }, "mappings": { "type": "array", "items": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "workspace_name": { "type": "string" }, "role": { "enum": [ "admin", "member" ] } } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Not on the Business or Enterprise plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteScimToken", "tags": [ "SCIM" ], "summary": "Stop directory sync", "description": "The token stops working. Provisioned people keep their seats. Not plan-gated.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "base_url": { "type": "string", "description": "The SCIM base URL to give your directory." }, "token": { "type": [ "object", "null" ], "description": "`{ prefix, created_at, last_used_at }`; the token itself is shown once, as `token_value` when created." }, "users": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "members": { "type": "integer" }, "mappings": { "type": "array", "items": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "workspace_name": { "type": "string" }, "role": { "enum": [ "admin", "member" ] } } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/scim/groups/{id}/workspaces/{workspaceId}": { "put": { "operationId": "mapScimGroup", "tags": [ "SCIM" ], "summary": "Map a directory group to a workspace", "description": "Members of the group get this role in the workspace; across several groups the highest role wins. Workspace roles only: a directory never grants an organisation role. Memberships set by hand are not changed. Business plan or above; Owner.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The directory group id.", "schema": { "type": "string" } }, { "name": "workspaceId", "in": "path", "required": true, "description": "The workspace id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "enum": [ "admin", "member" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "base_url": { "type": "string", "description": "The SCIM base URL to give your directory." }, "token": { "type": [ "object", "null" ], "description": "`{ prefix, created_at, last_used_at }`; the token itself is shown once, as `token_value` when created." }, "users": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "members": { "type": "integer" }, "mappings": { "type": "array", "items": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "workspace_name": { "type": "string" }, "role": { "enum": [ "admin", "member" ] } } } } } } } } } }, "required": [ "data" ] } } } }, "400": { "description": "role must be admin or member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "402": { "description": "Not on the Business or Enterprise plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "unmapScimGroup", "tags": [ "SCIM" ], "summary": "Remove a group mapping", "description": "Members lose the role it gave them in that workspace.", "security": [ { "managementKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The directory group id.", "schema": { "type": "string" } }, { "name": "workspaceId", "in": "path", "required": true, "description": "The workspace id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "base_url": { "type": "string", "description": "The SCIM base URL to give your directory." }, "token": { "type": [ "object", "null" ], "description": "`{ prefix, created_at, last_used_at }`; the token itself is shown once, as `token_value` when created." }, "users": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "members": { "type": "integer" }, "mappings": { "type": "array", "items": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "workspace_name": { "type": "string" }, "role": { "enum": [ "admin", "member" ] } } } } } } } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/ManagementUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/methods": { "get": { "operationId": "getAuthMethods", "tags": [ "Auth" ], "summary": "List the sign-in methods this deployment offers", "security": [], "x-auth": "public", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "management_key": { "const": true }, "oauth": { "type": "array", "items": { "enum": [ "google", "github" ] } }, "wallet": { "type": "boolean" }, "sso": { "type": "boolean", "description": "True once any organisation on this deployment has an active SSO connection: the sign-in page then offers \"Sign in with SSO\"." } } } }, "required": [ "data" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/oauth/{provider}/start": { "get": { "operationId": "startOAuth", "tags": [ "Auth" ], "summary": "Start signing in with Google or GitHub", "description": "A browser navigation, not an API call: redirects to the provider with PKCE and a state cookie (`ar_oauth`, ten minutes).", "security": [], "x-auth": "public", "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "The identity provider.", "schema": { "enum": [ "google", "github" ] } } ], "responses": { "302": { "description": "To the provider's consent screen.", "headers": { "Location": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound", "description": "That provider is not configured on this deployment." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/oauth/{provider}/callback": { "get": { "operationId": "finishOAuth", "tags": [ "Auth" ], "summary": "The OAuth redirect target", "description": "Always redirects: to `/workspace` with a session on success (`?welcome=1` for a new user), otherwise to `/signin?error=` with one of `cancelled`, `provider_error`, `expired`, `state_mismatch`, `no_code`, `not_configured`, `exchange_failed`.", "security": [], "x-auth": "The `state` matched to the `ar_oauth` cookie, and the provider's authorization code.", "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "The identity provider.", "schema": { "enum": [ "google", "github" ] } }, { "name": "code", "in": "query", "required": false, "description": "The authorization code.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Must match the `ar_oauth` cookie.", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Set by the provider when sign-in did not happen.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "To the dashboard.", "headers": { "Location": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/wallet/nonce": { "post": { "operationId": "createWalletNonce", "tags": [ "Auth" ], "summary": "Start signing in with a wallet", "description": "Returns a Sign-In with Ethereum message to sign. The challenge lasts five minutes.", "security": [], "x-auth": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "address" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "nonce": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] } } } }, "400": { "description": "`address must be a 0x-prefixed 20-byte hex string`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound", "description": "Wallet sign-in is not enabled." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/wallet/verify": { "post": { "operationId": "verifyWalletSignature", "tags": [ "Auth" ], "summary": "Finish signing in with a wallet", "description": "Sets the session cookies on success.", "security": [], "x-auth": "A wallet signature over a single-use nonce from POST /v1/auth/wallet/nonce.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "signature": { "type": "string" }, "nonce": { "type": "string" } }, "required": [ "address", "signature", "nonce" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time" }, "org_id": { "type": "string", "format": "uuid" }, "is_new_user": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "400": { "description": "A field is missing, or no valid challenge exists for this address and nonce: unknown, expired, or already used. The challenge is consumed by the attempt either way.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`Signature does not match the address`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound", "description": "Wallet sign-in is not enabled." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/health": { "get": { "operationId": "getHealth", "tags": [ "Meta" ], "summary": "Health", "description": "Public; for load balancers and uptime checks. A 500 means the database is unreachable.\n\nLiveness, the version this document already publishes, and whether the rate limiter is shared across instances — nothing here varies with account activity.", "security": [], "x-auth": "public", "responses": { "200": { "description": "Serving.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/csp-report": { "post": { "operationId": "cspReport", "tags": [ "Meta" ], "summary": "Receive a Content-Security-Policy violation report", "description": "For browsers, not for you: the dashboard's CSP names this path in `report-uri`. Accepts the legacy `application/csp-report` document and the Reporting API's `application/reports+json` array; the violation's document, directive, blocked URI and source are logged (each clipped to 200 characters, at most ten per report) and nothing is stored. Unauthenticated and rate-limited per address like the catalog.", "security": [], "x-auth": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "A CSP report in either wire format.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] } } } }, "responses": { "204": { "description": "Logged." }, "429": { "$ref": "#/components/responses/RateLimited" }, "451": { "$ref": "#/components/responses/RegionNotServed" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/geo": { "get": { "operationId": "getGeo", "tags": [ "Meta" ], "summary": "The caller's coarse region", "description": "As the edge reported it. The dashboard uses it to choose a language, so it is never refused by region.", "security": [], "x-auth": "public", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "region": { "type": [ "string", "null" ] }, "subdivision": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiJson", "tags": [ "Meta" ], "summary": "This document, as JSON", "security": [], "x-auth": "public", "responses": { "200": { "description": "The OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/openapi.yaml": { "get": { "operationId": "getOpenApiYaml", "tags": [ "Meta" ], "summary": "This document, as YAML", "security": [], "x-auth": "public", "responses": { "200": { "description": "The OpenAPI 3.1 document.", "content": { "application/yaml": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/openapi.json": { "get": { "operationId": "getOpenApiV1Json", "tags": [ "Meta" ], "summary": "This document, as JSON", "security": [], "x-auth": "public", "responses": { "200": { "description": "The OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/openapi.yaml": { "get": { "operationId": "getOpenApiV1Yaml", "tags": [ "Meta" ], "summary": "This document, as YAML", "security": [], "x-auth": "public", "responses": { "200": { "description": "The OpenAPI 3.1 document.", "content": { "application/yaml": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "inferenceKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ar-v1-…", "description": "An inference key. Makes model requests; refused on management routes." }, "scimToken": { "type": "http", "scheme": "bearer", "bearerFormat": "scim_…", "description": "The SCIM token from Settings → Directory sync. Only for /v1/scim/v2." }, "managementKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ar-mgmt-…", "description": "A management key. Administers the account; refused on inference routes." }, "session": { "type": "apiKey", "in": "cookie", "name": "ar_session", "description": "The dashboard session. It acts as the management key that created it, and on `/v1/chat/completions` as the org's playground key. A request with any method but GET also needs `x-csrf-token`, echoing the `ar_csrf` cookie." }, "linkToken": { "type": "apiKey", "in": "query", "name": "token", "description": "A single-purpose secret in a URL the gateway generated: a video job's callback URL, or a link in an email (confirm, unsubscribe). It opens that one resource and nothing else, is stored only as a hash, and a wrong one is answered like an unknown resource." }, "connectorEventsToken": { "type": "http", "scheme": "bearer", "description": "A connector install's events token, issued once by the install handshake. Only for POST /v1/connectors/events." }, "webhookSignature": { "type": "apiKey", "in": "header", "name": "x-autonomous-relay-signature", "description": "`t=,v1=.\">` under the webhook trigger's signing secret, valid for five minutes." }, "stripeSignature": { "type": "apiKey", "in": "header", "name": "stripe-signature", "description": "Stripe's webhook signature over the raw body." } }, "parameters": { "CsrfToken": { "name": "x-csrf-token", "in": "header", "required": false, "description": "Required with a session cookie on any method but GET: the value of the `ar_csrf` cookie. Not used with a bearer key.", "schema": { "type": "string" } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer" } }, "RateLimitLimitRequests": { "description": "The key's `rpm_limit`. Only on a key that has one.", "schema": { "type": "integer" } }, "RateLimitRemainingRequests": { "description": "Requests left this minute under the key's `rpm_limit`.", "schema": { "type": "integer" } }, "RateLimitResetRequests": { "description": "When the minute ends, in Unix seconds.", "schema": { "type": "integer" } }, "RateLimitLimitTokens": { "description": "The key's `tpm_limit`. Only on a key that has one.", "schema": { "type": "integer" } }, "RateLimitRemainingTokens": { "description": "Tokens left this minute under the key's `tpm_limit`, before this request's own.", "schema": { "type": "integer" } }, "RateLimitResetTokens": { "description": "When the minute ends, in Unix seconds.", "schema": { "type": "integer" } } }, "responses": { "InferenceUnauthorized": { "description": "No key; an invalid, disabled or expired key; or an invalid session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InferenceForbidden": { "description": "A management key, or a dashboard session where only an inference key will do; or a session request without a valid `x-csrf-token`. The body reports `code: 403` and `permission_denied`. (Until 2026-09-27 it carried the 401 envelope; `ERRORS.fromAuth` now decides the envelope from the status.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ManagementUnauthorized": { "description": "No key; an invalid, disabled or expired key; or an invalid session. The body reports `code: 401` and `invalid_credentials`. (Until 2026-09-27 every management route sent the 403 envelope here; `requireManagementKey` in lib/auth.ts now decides the envelope from the status.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ManagementForbidden": { "description": "An inference key on a management route, or a session request without a valid `x-csrf-token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found, or not in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PlanRequired": { "description": "`subscription_required`: the organisation's plan does not include this. The message names the plan it needs; what was set up keeps working.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limited. `X-RateLimit-Reset` says when the window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "description": "Seconds.", "schema": { "type": "integer" } } } }, "KeyRateLimited": { "description": "Rate limited (`rate_limited`): by the account's quota (`X-RateLimit-*`), or by the key's own `rpm_limit` or `tpm_limit` (`X-RateLimit-*-Requests`, `X-RateLimit-*-Tokens`; the message names which). `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-RateLimit-Limit-Requests": { "$ref": "#/components/headers/RateLimitLimitRequests" }, "X-RateLimit-Remaining-Requests": { "$ref": "#/components/headers/RateLimitRemainingRequests" }, "X-RateLimit-Reset-Requests": { "$ref": "#/components/headers/RateLimitResetRequests" }, "X-RateLimit-Limit-Tokens": { "$ref": "#/components/headers/RateLimitLimitTokens" }, "X-RateLimit-Remaining-Tokens": { "$ref": "#/components/headers/RateLimitRemainingTokens" }, "X-RateLimit-Reset-Tokens": { "$ref": "#/components/headers/RateLimitResetTokens" }, "Retry-After": { "description": "Seconds.", "schema": { "type": "integer" } } } }, "RegionNotServed": { "description": "Refused by jurisdiction: the edge reported a subdivision this service does not operate in yet. **`code` is a string here, and there is no `metadata`.**", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionNotServed" } } } }, "InternalError": { "description": "An unexpected failure. `metadata.request_id` identifies it in our logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ErrorDetail": { "type": "object", "properties": { "code": { "type": "integer", "description": "Usually the HTTP status. Where it is not, the operation says so." }, "message": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "error_type": { "enum": [ "invalid_request", "context_length_exceeded", "invalid_credentials", "insufficient_credits", "permission_denied", "guardrail_blocked", "budget_exceeded", "run_budget_exceeded", "moderation_flagged", "not_found", "no_endpoints_available", "request_timeout", "payload_too_large", "rate_limited", "internal_error", "provider_error", "provider_overloaded", "provider_unreachable", "service_unavailable", "subscription_required", "sso_required", "method_not_allowed" ] }, "provider_code": { "description": "The upstream provider's own error code, preserved." }, "provider_name": { "type": "string" }, "model": { "type": "string" }, "unsatisfied_filters": { "type": "array", "items": { "type": "string" }, "description": "The filters that emptied the candidate set." }, "request_id": { "type": "string" } } } }, "required": [ "code", "message" ] }, "Error": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "error" ] }, "AnthropicError": { "type": "object", "properties": { "type": { "const": "error" }, "error": { "type": "object", "properties": { "type": { "enum": [ "invalid_request_error", "authentication_error", "billing_error", "permission_error", "not_found_error", "request_too_large", "rate_limit_error", "overloaded_error", "api_error" ] }, "message": { "type": "string" }, "metadata": { "type": "object", "description": "Our own detail, as on every other route: `error_type`, and the request id where there is one." } }, "required": [ "type", "message" ] } }, "required": [ "type", "error" ] }, "RegionNotServed": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "const": "region_not_served" }, "message": { "type": "string" }, "subdivision": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Deleted": { "type": "object", "properties": { "deleted": { "const": true } }, "required": [ "deleted" ] }, "ChatMessage": { "type": "object", "properties": { "role": { "enum": [ "system", "developer", "user", "assistant", "tool" ] }, "content": { "description": "A string, or an array of content parts as in OpenAI." }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_call_id": { "type": "string", "description": "On a `tool` message: the call it answers." } }, "required": [ "role" ], "additionalProperties": true }, "ProviderPreferences": { "type": "object", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Provider slugs to try first, in order. Reorders; excludes nothing." }, "only": { "type": "array", "items": { "type": "string" }, "description": "Route only to these providers." }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Never route to these providers." }, "sort": { "enum": [ "price", "throughput", "latency", "exacto" ], "description": "`price` cheapest first; `throughput` and `latency` fastest measured first; `exacto` most reliable tool calls first (§6.4's measured rate, then latency, then price). With tools and no sort, Exacto orders the endpoints once any of them has a measured rate; `price` or `:floor` opts out." }, "allow_fallbacks": { "type": "boolean", "default": true }, "require_parameters": { "type": "boolean", "description": "Only endpoints that declare support for every parameter the request sends: `tools`, `tool_choice`, `response_format`, `seed`, the sampling parameters, `stop`, `logprobs`, `logit_bias`, `max_tokens` and `reasoning`. An endpoint that declares no parameter set is not excluded." }, "preferred_max_latency": { "type": "number", "exclusiveMinimum": 0, "description": "Seconds. A **soft** reorder: endpoints whose measured average latency is above it are tried after the rest; nothing is excluded, and an unmeasured endpoint keeps its place. A percentile object is a 400: only an average is measured." }, "preferred_min_throughput": { "description": "Accepted, and has no effect yet: no endpoint's throughput is measured, so none can be deprioritised for missing it." }, "data_collection": { "enum": [ "allow", "deny" ], "description": "`deny` is a 400: we do not record providers' training terms, which are set by your own agreement with the provider. `allow` is accepted and changes nothing." }, "zdr": { "type": "boolean", "description": "`true` is a 400: we do not record whether a provider retains prompts, which is set by your own agreement with the provider. `false` is accepted and changes nothing." }, "quantizations": { "type": "array", "items": { "type": "string" } }, "max_price": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Ceilings by SKU, in USD per million tokens." }, "min_tool_success_rate": { "type": "number", "minimum": 0, "maximum": 1, "description": "§17.3. A **hard** filter on §6.4's measured tool-call reliability: `0.98` admits only endpoints whose tool calls come back valid at least 98% of the time.\n\nA success rate, not the error rate `tool_call_error_rate` publishes — this is the way a requirement is stated. An endpoint below the 100-request sample floor has **no measured rate and passes**: refusing unmeasured endpoints would make the knob unusable the day a provider adds capacity, and treating them as perfect would be a silent lie. When the filter does bite, `metadata.unsatisfied_filters` says so and names the threshold." } }, "description": "Routing preferences (§6.2). Preferences reorder; constraints reject. Guardrails outrank everything here." }, "ChatCompletionRequest": { "type": "object", "description": "The OpenAI Chat Completions body, plus routing fields. Parameters an endpoint does not support are dropped for that endpoint, not rejected (FR-NORM-5).", "additionalProperties": true, "allOf": [ { "anyOf": [ { "required": [ "model" ] }, { "required": [ "models" ] } ] }, { "anyOf": [ { "required": [ "messages" ] }, { "required": [ "prompt" ] } ] } ], "properties": { "model": { "type": "string", "description": "A catalog id, `author/slug`, optionally with a variant (`:free`, `:nitro`, `:floor`, `:exacto`), or a `~author/family` alias, which resolves to the `author/family-latest` row when the catalog publishes one and otherwise resolves to nothing -- it never picks a model for you by guessing at the name. An id listed in `/v1/models` always means that listing: some free tiers are catalog rows of their own, named `author/slug:free`, and a suffix is only split off the id when no such row can serve the request. It always applies as a variant either way. Or `@preset/` (`@` to pin one): your organisation's preset, whose settings fill in whatever this request does not set." }, "models": { "type": "array", "items": { "type": "string" }, "description": "A fallback chain, tried in order. At most three are attempted." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "prompt": { "type": "string", "description": "Legacy: sent as a single user message when `messages` is absent." }, "stream": { "type": "boolean", "default": false }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "max_completion_tokens": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "seed": { "type": "integer" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Client functions, and server tools the gateway runs itself: `{\"type\": \"autonomousrelay:datetime\", \"parameters\": {\"timezone\": \"America/Toronto\"}}`, `{\"type\": \"autonomousrelay:experimental__search_models\"}`, or a registered MCP server's tools: `{\"type\": \"autonomousrelay:mcp\", \"server\": \"\", \"allowed_tools\": [...]}` (§17.7; see POST /v1/mcp-servers), offered to the model as `mcp____` and called by the gateway on the server's credential. An installed marketplace plugin's tools: `{\"type\": \"autonomousrelay:plugin\", \"plugin\": \"\", \"allowed_tools\": [...]}` (see POST /v1/plugins/{id}/install), offered as `plugin____` and called on the install's own credential -- `{\"type\": \"autonomousrelay:plugin\", \"plugin\": \"notion\"}` offers `plugin__notion__search_pages` and `plugin__notion__read_page`; a plugin not installed is a 404, one turned off a 403, one that cannot list its tools a 502. Every connection at once: `{\"type\": \"autonomousrelay:connected\", \"include\": [...], \"exclude\": [...], \"writes\": [...]}` offers the READ tools of every installed plugin and MCP server (at most 10 connections and 128 functions per request), plus only the write tools named exactly in `writes` -- which need a `run_id` whose agent has an approval policy, and always wait for a person. A connection that does not work (not connected, expired, turned off, unreachable) is skipped, not an error: the answer comes from the rest, the `X-Autonomous-Relay-Connected-Tools` response header and `agentrouter_metadata.connected_tools` say what was used and skipped, and the organisation's alert channels (or its owners, by email) are told once a day per connection. GET /v1/tools/available shows what it would draw on. With `\"stream\": true` the loop still runs: its progress arrives as SSE comment lines (`: autonomousrelay {\"type\": \"tool.called\", ...}`, which SDKs ignore), then the answer as ordinary chunks. Their use is reported in `usage.server_tool_use`. See GET /v1/tools for the catalogue and which are available." }, "max_tool_calls": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30, "description": "The most server-tool executions this request may make." }, "tool_context": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 }, "maxProperties": 10, "description": "Context for connector tools: a plugin tool whose connector manifest declares a key receives that key's value as `_context`. A hosted agent's run started by a connector event sets it from the event. Never sent to the model provider." }, "tool_choice": { "description": "`none`, `auto`, `required`, or `{\"type\": \"function\", \"function\": {\"name\": …}}`." }, "service_tier": { "enum": [ "auto", "default", "flex", "priority", "fast", "scale" ], "description": "OpenAI's processing tier. `flex` (Batch rates; OpenAI may refuse it with a 429 when busy, uncharged) and `priority` / `fast` (Fast mode, a per-token premium) are sent only to an OpenAI endpoint with a published price for that tier; anywhere else the request is served at standard. Billing follows the tier the provider reports serving at -- a Fast request OpenAI serves at default is billed at default. `auto`, `default` and `scale` are accepted and not forwarded." }, "response_format": { "type": "object", "additionalProperties": true, "description": "`{\"type\": \"json_object\"}` or `{\"type\": \"json_schema\", \"json_schema\": {\"name\", \"schema\", \"strict\"}}`. Passed as is on OpenAI-protocol providers; on Gemini it becomes JSON mode with the schema; on Anthropic a `json_schema` becomes structured outputs, with the bounds Anthropic does not enforce (`minimum`, `maxLength`, `maxItems`, …) left unchecked and `additionalProperties: false` assumed where unset. A schema Anthropic cannot express (`additionalProperties` other than false, a recursive or external `$ref`) is sent there without a format; `json_object` has no Anthropic counterpart. The `response-healing` plugin repairs a reply that is still not JSON." }, "plugins": { "type": "array", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "enum": [ "response-healing", "context-compression", "file-parser", "auto-router", "moderation", "web" ] }, "enabled": { "type": "boolean" }, "input": { "type": "boolean" }, "output": { "type": "boolean" }, "engine": { "enum": [ "native" ] }, "max_uses": { "type": "integer" }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "excluded_domains": { "type": "array", "items": { "type": "string" } }, "pdf": { "type": "object", "properties": { "engine": { "enum": [ "pdf-text", "native" ] } } }, "cost_tier": { "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "excluded_models": { "type": "array", "items": { "type": "string" } } } }, "description": "`[{\"id\": \"response-healing\"}]` repairs a reply that should have been JSON (`response_format` `json_object` or `json_schema`): markdown fences, surrounding text, trailing commas, comments, bare keys, unclosed brackets. The repair is used only if it parses; a reply that already is JSON, or that `max_tokens` cut short (`finish_reason: \"length\"`), is returned as written. Not on streams. When it changed the answer, `agentrouter_metadata.pipeline` includes `response_healing`.\n\n`{\"id\": \"context-compression\"}` fits a conversation to the serving endpoint's context window by removing whole messages from the middle out: system and developer messages, the first message and the last always stay, and a tool call goes with its results. The window left for the prompt is the context less `max_tokens` (a quarter of the window when unset). On by default for endpoints of 8,192 tokens or less; `{\"id\": \"context-compression\", \"enabled\": false}` turns it off. With it on, Anthropic's 1,000-message limit is met the same way. Never applied to an image-output model. A failover to a larger endpoint sends the conversation whole. When it removed messages, `pipeline` includes `context_compression`.\n\n`{\"id\": \"file-parser\", \"pdf\": {\"engine\": \"pdf-text\" | \"native\"}}` decides how a PDF `file` part (`file_data` as a base64 data URL, or a `file_id`) reaches the model. `native` sends the file; `pdf-text` sends its text layer, read on our side, as a text part headed by the filename, page by page (at most 200 pages and 1,000,000 characters per request). Unset, each endpoint decides: the file where the model reads files, its text everywhere else, so PDFs work on any model. `mistral-ocr` is refused: OCR would send the document to a third party, so a scanned PDF has no text here and should go to a model that reads PDFs. A file that is not a PDF, or is password-protected, is a 400 when an endpoint needs its text. When the model was given text, the answer carries it as `message.annotations` (on a stream, on the final chunk's `delta.annotations`) `[{\"type\": \"file\", \"file\": {\"hash\", \"name\", \"content\": [{\"type\": \"text\", \"text\"}]}}]`; send that assistant message back with the conversation and the annotation is used instead of reading the file again. `pipeline` includes `file_parser`. Nothing is stored.\n\n`{\"id\": \"auto-router\", \"cost_tier\": \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\", \"allowed_models\": [...], \"excluded_models\": [...]}` configures `\"model\": \"autonomousrelay/auto\"`: a paid model you can route to that fits the request (text out, image input when an image is sent, a window that holds it), from the tier by output price per million tokens (low to $2, the default; medium to $10; high to $30; xhigh to $60; max above), the most expensive first, then the newest; two fallbacks from the same tier; the nearest cheaper tier when the one asked for has nothing, then the nearest dearer one. Patterns take `*` for any run of characters. The prompt is not read and nothing is kept, so the same request picks the same model.\n\n`{\"id\": \"moderation\", \"input\": true, \"output\": false}` checks the input (default) and, with `output: true`, the answer, using OpenAI's `omni-moderation-latest` on the organisation's own OpenAI BYOK key (a 400 without one). The input is checked before any provider sees it and before anything is held; a flag is a 403 with `error_type` `moderation_flagged` and metadata `{reasons, flagged_input, provider_name, model_slug}`. A flagged answer is withheld, and the request is billed because the model ran. Output moderation is refused on streams. If moderation cannot run, the request is refused (503), never sent unchecked. `pipeline` includes `moderation`.\n\n`{\"id\": \"web\", \"engine\": \"native\", \"max_uses\": 3, \"allowed_domains\": [...] | \"excluded_domains\": [...]}` lets the model search the web with its **provider's own** search: Anthropic's web search tool on Claude models, Google Search grounding on Gemini 3 models, and OpenAI's and xAI's `web_search` tool (the request is run on their Responses API) on GPT-5 and later and Grok 4 models. Gemini 2.5 is not served: it is priced per grounded prompt. Only those endpoints are candidates; with none, a 404. `max_uses` (1-20) applies on Claude; the domain lists on Claude, OpenAI and xAI (at most 5 on xAI), so a request with domains never goes to Gemini. Each search is metered as a `web_search` line at the provider's published price per 1,000: $10 Anthropic, $14 Gemini (before Google's free monthly allowance), $10 OpenAI, $5 xAI. The pages the search cited come back as `url_citation` annotations on the message (on a stream, in `delta.annotations` as they arrive), with `start_index`/`end_index` where the provider gives character offsets. Outside engines (Exa and the like) are refused: they would be a new recipient of your queries. Other plugin ids are ignored." }, "reasoning": { "type": "object", "additionalProperties": true, "description": "`{ effort: minimal|low|medium|high|xhigh|max }` or `{ max_tokens: n }`. On Anthropic's current models (Fable, Opus 4.6 and later, Sonnet 4.6 and later) this becomes adaptive thinking with `effort` as the depth (`minimal` is `low`; `xhigh` is `high` on the 4.6 models); a `max_tokens` budget turns thinking on at the model's default depth, since those models size their thinking inside the request's own `max_tokens`. On older Claude models it is extended thinking with that budget (floor 1024). Either way the thinking text is returned as `message.reasoning` (or `delta.reasoning` when streaming). `temperature`, `top_p` and `top_k` are dropped alongside thinking, and on Fable, Opus 4.7 and later and Sonnet 5 always, because Anthropic refuses them there." }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" }, "session_id": { "type": "string", "description": "Keeps a conversation on one endpoint so its prompt cache stays warm (§6.6).", "maxLength": 256 }, "prompt_cache_key": { "type": "string", "description": "Used as the sticky-routing key when there is no `session_id`." }, "routing_stability": { "enum": [ "adaptive", "sticky", "pinned" ], "description": "Defaults to `sticky` when the request has a pin key, `adaptive` otherwise (§17.2)." } } }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "prompt_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer" }, "cache_write_tokens": { "type": "integer" } } }, "completion_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "integer" } } }, "cost": { "type": "number", "description": "What this request cost you, in USD. On a BYOK request, the platform fee." }, "is_byok": { "type": "boolean" }, "cost_details": { "type": "object", "properties": { "upstream_inference_cost": { "type": [ "number", "null" ], "description": "What your provider charged, in USD, on a BYOK request." }, "server_tool_cost": { "type": "number" } } }, "cached": { "type": "boolean", "description": "Present and true when the answer came from the response cache: the token counts are the original answer's, and `cost` is 0." } }, "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ] }, "RouterMetadata": { "type": "object", "properties": { "requested": { "type": "string", "description": "The slug the client asked for." }, "strategy": { "enum": [ "direct", "auto", "free", "latest", "alias", "fallback", "pareto", "bodybuilder", "fusion" ] }, "region": { "type": "string" }, "attempt": { "type": "integer", "description": "The 1-indexed attempt that served." }, "is_byok": { "type": "boolean" }, "summary": { "type": "string", "description": "A one-line account of the decision." }, "endpoints": { "type": "object", "properties": { "total": { "type": "integer", "description": "Endpoints that existed before your constraints filtered them." }, "available": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "selected": { "type": "boolean" } } } } } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "endpoint_id": { "type": "string" }, "status": { "enum": [ "ok", "error" ] }, "error": { "type": "string" }, "is_byok": { "type": "boolean" }, "duration_ms": { "type": "integer", "description": "Time inside the provider call. Absent when the attempt never reached one." }, "ttft_ms": { "type": [ "integer", "null" ], "description": "Time to first token, on the attempt that streamed." }, "http_status": { "type": [ "integer", "null" ], "description": "The upstream status, where the provider answered at all." }, "error_code": { "type": [ "string", "null" ], "description": "The provider's own code, preserved." }, "reason_code": { "type": [ "string", "null" ], "description": "Why THIS gateway failed the attempt, as a stable `router.*` code, when the failure was ours rather than the provider's. Absent when a provider answered." } } } }, "params": { "type": "object", "additionalProperties": true }, "pipeline": { "type": "array", "items": { "enum": [ "guardrail", "plugin", "server_tools", "response_healing", "context_compression", "file_parser", "moderation" ] } }, "sticky": { "type": "object", "properties": { "stability": { "enum": [ "adaptive", "sticky", "pinned" ] }, "pin_source": { "enum": [ "session_id", "x-session-id", "prompt_cache_key", "prefix_hash" ] }, "hit": { "type": "boolean" }, "miss_reason": { "enum": [ "not_eligible", "unhealthy", "adaptive" ] } } }, "tool_calls": { "type": "object", "properties": { "calls": { "type": "integer", "description": "How many tool calls this generation produced." }, "error_kind": { "type": [ "string", "null" ], "enum": [ "invalid_json", "unknown_name", "schema_mismatch", null ], "description": "The FIRST failure kind (§6.4 scores the request, not each call). Null when every call validated." }, "offending_name": { "type": [ "string", "null" ], "description": "The function name that failed." }, "offending_path": { "type": [ "string", "null" ], "description": "For `schema_mismatch`, where inside the arguments it failed — `/city`, `/filters/0/op`. The **path only**; the value at it is your data and is never echoed. Null for the other kinds: unparseable arguments have no path, and an unknown name is wrong at the call rather than within it." } }, "required": [ "calls", "error_kind" ], "description": "§17.3 per-generation tool-call diagnostics. Present only when the generation produced tool calls — including when they all validated, because that is the evidence your schema and the provider are both fine." } }, "description": "Why this model, this provider, this price (§7.5). Present only when `X-Autonomous-Relay-Metadata: enabled` was sent." }, "ChatCompletion": { "type": "object", "properties": { "id": { "type": "string", "description": "`gen-…`. Pass it to `GET /v1/generation` for the full record." }, "object": { "const": "chat.completion" }, "created": { "type": "integer", "description": "Unix seconds." }, "model": { "type": "string", "description": "The model that served, which differs from the one requested when a fallback fired." }, "provider": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "const": "assistant" }, "content": { "type": "string" }, "reasoning": { "type": "string", "description": "Extended-thinking text, when the request asked for `reasoning` and the provider returned it." }, "tool_calls": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", "content_filter", "error", null ], "description": "Normalized to five values. `native_finish_reason` carries the provider's own." }, "native_finish_reason": { "type": [ "string", "null" ] } } } }, "usage": { "$ref": "#/components/schemas/Usage" }, "agentrouter_metadata": { "$ref": "#/components/schemas/RouterMetadata" } }, "required": [ "id", "object", "created", "model", "choices", "usage" ] }, "ChatCompletionChunk": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "chat.completion.chunk" }, "created": { "type": "integer" }, "model": { "type": "string" }, "provider": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "delta": { "type": "object", "properties": { "content": { "type": "string" }, "reasoning": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", "content_filter", "error", null ], "description": "Normalized to five values. `native_finish_reason` carries the provider's own." }, "native_finish_reason": { "type": [ "string", "null" ] } } } }, "usage": { "$ref": "#/components/schemas/Usage", "description": "On the final chunk before `[DONE]`, always." }, "agentrouter_metadata": { "$ref": "#/components/schemas/RouterMetadata" }, "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "A failure after the stream started. The HTTP status is already 200, so it arrives here, with `finish_reason: \"error\"`." } }, "required": [ "id", "object", "created", "model", "choices" ] }, "Model": { "type": "object", "properties": { "id": { "type": "string", "description": "`author/slug`." }, "canonical_slug": { "type": "string" }, "name": { "type": "string" }, "created": { "type": [ "integer", "null" ], "description": "Unix seconds." }, "description": { "type": [ "string", "null" ] }, "context_length": { "type": [ "integer", "null" ] }, "architecture": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Input and output modalities." }, "supported_parameters": { "type": [ "array", "null" ], "items": { "type": "string" } }, "default_parameters": { "type": [ "object", "null" ], "additionalProperties": true }, "resale_permitted": { "enum": [ "yes", "no", "via_reseller", "unknown" ] }, "byok_only": { "type": "boolean" }, "is_free": { "type": "boolean" }, "deprecation_date": { "type": [ "string", "null" ] }, "pricing": { "type": "object", "properties": { "prompt": { "type": "string", "description": "US dollars as a decimal string, so no precision is lost in JSON." }, "completion": { "type": "string", "description": "US dollars as a decimal string, so no precision is lost in JSON." } }, "description": "The cheapest endpoint's price. Present on the list only." } }, "required": [ "id", "name" ] }, "ModelEndpoint": { "type": "object", "properties": { "name": { "type": "string" }, "model_id": { "type": "string" }, "provider_name": { "type": "string" }, "provider_slug": { "type": "string" }, "tag": { "type": "string", "description": "The name this provider knows the model by, which is what we send as `model` when we dispatch. It is the catalog id for a provider re-serving someone else, and the slug alone for a lab that names its own models bare." }, "quantization": { "type": [ "string", "null" ] }, "context_length": { "type": [ "integer", "null" ] }, "max_completion_tokens": { "type": [ "integer", "null" ] }, "pricing": { "type": "object", "description": "Prices by SKU, plus `overrides` when the endpoint has conditional prices.", "properties": { "overrides": { "type": "array", "description": "Conditional prices (§7.8), tried in order; the first whose conditions all hold replaces the listed SKUs' prices for that request, judged at its start. `min_prompt_tokens`: the prompt, cached tokens included, is at least this long (a long-context tier). `utc_start`/`utc_end`: a UTC time-of-day window, \"HH:MM\", start inclusive, end exclusive, wrapping midnight when the end is earlier. `utc_days`: 0 (Sunday) to 6. Every other key is a SKU and its price in that case.", "items": { "type": "object", "properties": { "min_prompt_tokens": { "type": "integer", "minimum": 1 }, "utc_start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "utc_end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "utc_days": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "additionalProperties": { "type": "string", "description": "US dollars as a decimal string, so no precision is lost in JSON." } } } }, "additionalProperties": { "type": "string", "description": "US dollars as a decimal string, so no precision is lost in JSON." } }, "supported_parameters": { "type": [ "array", "null" ], "items": { "type": "string" } }, "supports_tool_choice": { "type": [ "boolean", "null" ] }, "supports_implicit_caching": { "type": [ "boolean", "null" ] }, "status": { "description": "The endpoint's status as recorded in the catalog." }, "deployment_region": { "type": [ "string", "null" ] }, "uptime": { "anyOf": [ { "type": "object", "properties": { "5m": { "type": [ "number", "null" ] }, "30m": { "type": [ "number", "null" ] }, "1d": { "type": [ "number", "null" ] }, "samples": { "type": "integer" }, "tier": { "type": "string" }, "avg_latency_ms": { "type": [ "number", "null" ] } } }, { "type": "null" } ], "description": "Measured, with the caller's own errors excluded (§8.2)." }, "tool_call_error_rate": { "type": [ "number", "null" ], "description": "§6.4: the share of tool calls that failed validation against the caller's schema." }, "tool_call_requests": { "type": [ "integer", "null" ] } } }, "Provider": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "hq_country": { "type": [ "string", "null" ] }, "datacenters": { "type": [ "array", "null" ], "items": { "type": "string" } }, "privacy_policy_url": { "type": [ "string", "null" ] }, "tos_url": { "type": [ "string", "null" ] }, "status_page_url": { "type": [ "string", "null" ] }, "models_served": { "type": "integer", "description": "In `GET /v1/providers` only: how many ready models the provider has an active endpoint for -- the models `GET /v1/providers/{slug}` lists. Zero for a provider in the directory that serves nothing yet." } }, "required": [ "slug", "name" ] }, "KeyInfo": { "type": "object", "properties": { "label": { "type": [ "string", "null" ] }, "limit": { "type": [ "number", "null" ], "description": "The key's spend limit in USD, or null for none." }, "limit_remaining": { "type": [ "number", "null" ], "description": "Ceiling minus usage, measured exactly as the spend gate measures it: within the reset window, including spend on your own provider credential only when include_byok_in_limit is set, plus the worst-case reservation of every request on this key still in flight -- released or replaced by the actual amount at settlement, so this can go down. Not a billing total -- see /v1/credits for money." }, "usage": { "type": "number", "description": "Spend counted against this key ceiling, measured exactly as the spend gate measures it: within the reset window, including spend on your own provider credential only when include_byok_in_limit is set, plus the worst-case reservation of every request on this key still in flight -- released or replaced by the actual amount at settlement, so this can go down. Not a billing total -- see /v1/credits for money." }, "limit_reset": { "type": [ "string", "null" ] }, "limit_mode": { "enum": [ "hard", "soft" ], "description": "`hard` (the default) refuses a request once the key is at or past its ceiling, with 403 `budget_exceeded`. `soft` serves it and adds an `x-autonomous-relay-limit-warning` header carrying the same sentence." }, "include_byok_in_limit": { "type": "boolean", "description": "Count spend made on your own provider credential toward this ceiling, at IMPUTED LIST PRICE -- what the call would have cost on platform capacity, not the platform fee charged. Defaults to true: every model is BYOK-only, so a ceiling that skipped this spend would count nothing and could never bind. Set false to count only platform spend." }, "rpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000, "description": "The key's own requests per minute, counted in calendar minutes on top of the account quota; null for none. Inference keys only." }, "tpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000000, "description": "The key's own tokens (prompt + completion) per minute; null for none. Requests are refused once the minute's count reaches it, and a request's tokens are counted when it finishes, so requests in flight can overshoot it. Inference keys only." }, "is_free_tier": { "type": "boolean" } } }, "Branding": { "type": "object", "properties": { "org_name": { "type": "string", "description": "The organisation's own name; the fallback when brand_name is unset." }, "brand_name": { "type": [ "string", "null" ] }, "brand_logo": { "type": [ "string", "null" ], "description": "A PNG or JPEG data URI." }, "brand_footer": { "type": [ "string", "null" ] } } }, "ReportLine": { "type": "object", "properties": { "requests": { "type": "integer" }, "errors": { "type": "integer" }, "tokens": { "type": "integer" }, "list_price_usd": { "type": "number", "description": "US dollars." } } }, "Workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ], "description": "Up to 500 characters." }, "your_role": { "type": [ "string", "null" ], "description": "The caller's workspace role when their seat is limited to workspaces; null for a seat that sees the whole organisation." }, "created_at": { "type": "string", "format": "date-time" }, "active_keys": { "type": "integer" }, "spend_this_month": { "type": "number", "description": "USD, current UTC calendar month, measured as a workspace budget measures it." }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "interval": { "enum": [ "daily", "weekly", "monthly", "lifetime" ] }, "limit": { "type": "number", "description": "US dollars." }, "include_byok": { "type": "boolean" } } } }, "is_current": { "type": "boolean", "description": "Whether this is the calling key's own workspace." } } }, "AlertChannel": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "enum": [ "webhook", "slack", "email" ] }, "target": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "thresholds": { "type": "array", "items": { "type": "integer" } }, "events": { "type": "array", "items": { "enum": [ "usage", "price_drop" ] }, "description": "What the channel receives. `usage` (the default): key and agent limit crossings and runaway flags. `price_drop`: a model this organisation used in the last 30 days got cheaper (input or output tokens), announced once, within 15 minutes of the change." }, "disabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "AlertDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "channel_id": { "type": [ "string", "null" ], "description": "Null once the channel has been removed." }, "channel_name": { "type": [ "string", "null" ] }, "channel_kind": { "type": [ "string", "null" ] }, "event": { "enum": [ "key_limit.threshold", "agent_limit.threshold", "spend.runaway", "run.paused", "connection.skipped", "price_drop", "ledger.drift", "test" ] }, "threshold": { "type": [ "integer", "null" ] }, "status": { "enum": [ "sent", "failed", "skipped" ] }, "http_status": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "key_name": { "type": [ "string", "null" ] }, "key_hash_prefix": { "type": [ "string", "null" ] }, "agent_tag": { "type": [ "string", "null" ], "description": "For an agent-budget alert: the X-Autonomous-Relay-Agent value." }, "created_at": { "type": "string", "format": "date-time" } } }, "ApiKey": { "type": "object", "properties": { "hash": { "type": "string", "description": "Identifies the key in `DELETE /v1/keys/{hash}`. Not the key itself." }, "prefix": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "class": { "enum": [ "inference", "management" ] }, "disabled": { "type": "boolean" }, "limit": { "type": [ "number", "null" ], "description": "USD." }, "limit_nanodollars": { "type": [ "string", "null" ], "description": "The same limit, raw." }, "limit_reset": { "type": [ "string", "null" ] }, "limit_mode": { "enum": [ "hard", "soft" ], "description": "`hard` (the default) refuses a request once the key is at or past its ceiling, with 403 `budget_exceeded`. `soft` serves it and adds an `x-autonomous-relay-limit-warning` header carrying the same sentence." }, "include_byok_in_limit": { "type": "boolean" }, "rpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000, "description": "The key's own requests per minute, counted in calendar minutes on top of the account quota; null for none. Inference keys only." }, "tpm_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000000, "description": "The key's own tokens (prompt + completion) per minute; null for none. Requests are refused once the minute's count reaches it, and a request's tokens are counted when it finishes, so requests in flight can overshoot it. Inference keys only." }, "cache_enabled": { "type": "boolean", "description": "Whether this key's non-streaming chat completions are answered from the response cache. Off by default." }, "cache_ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "How long an answer stays cached. Kept while the cache is off." }, "workspace_id": { "type": [ "string", "null" ], "description": "The workspace (client) the key belongs to." }, "usage": { "type": [ "number", "null" ], "description": "USD counted against the ceiling in its current window, measured exactly as the spend gate measures it (see KeyInfo.usage). Null for a key with no ceiling, or a revoked one." }, "limit_remaining": { "type": [ "number", "null" ], "description": "Ceiling minus usage. Negative when a soft ceiling has been passed. Null when there is no ceiling." }, "limit_resets_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the current window ends. Null for a lifetime ceiling or none." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_user": { "type": [ "string", "null" ] } } }, "ActivityItem": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "requested_model": { "type": "string" }, "served_model": { "type": [ "string", "null" ], "description": "Null until routing picks one; differs from `requested_model` when a fallback fired." }, "provider_slug": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", "content_filter", "error", null ], "description": "Normalized to five values. `native_finish_reason` carries the provider's own." }, "native_finish_reason": { "type": [ "string", "null" ] }, "is_byok": { "type": "boolean" }, "is_cache_hit": { "type": "boolean" }, "cancelled": { "type": "boolean" }, "streamed": { "type": "boolean" }, "quantization": { "type": [ "string", "null" ] }, "ttft_ms": { "type": [ "integer", "null" ] }, "generation_ms": { "type": [ "integer", "null" ] }, "routing_overhead_ms": { "type": [ "integer", "null" ], "description": "Total time minus upstream provider time -- the latency this gateway added (§18). Null when nothing was dispatched, and on rows recorded before it was measured." }, "error_code": { "type": [ "string", "null" ], "description": "The provider's own code where a provider refused, or a `router.*` reason code where this gateway is what failed -- a credential it could not open, a request it could not express. A stream that broke after it had committed is recorded on the upstream attempt, not here." }, "error_message": { "type": [ "string", "null" ], "description": "The failure in English, for a developer. Where a provider refused, this names the provider, its HTTP status and its error code -- never the provider's own text, which can quote the prompt and is returned only in the response to the request itself. Where this gateway failed, its own sentence." }, "total_cost": { "type": "number", "description": "US dollars." }, "app_id": { "type": [ "string", "null" ] }, "app_title": { "type": [ "string", "null" ] }, "http_referer": { "type": [ "string", "null" ] }, "workspace_id": { "type": [ "string", "null" ], "description": "The client (workspace) of the key that made the request." }, "agent": { "type": [ "string", "null" ], "description": "The X-Autonomous-Relay-Agent the request named, if any." }, "tags": { "type": "array", "items": { "type": "string", "description": "A tag a classifier gave the request." } } } }, "ActivityDetail": { "allOf": [ { "$ref": "#/components/schemas/ActivityItem" }, { "type": "object", "properties": { "endpoint_id": { "type": [ "string", "null" ] }, "moderation_ms": { "type": [ "integer", "null" ] }, "router": { "type": [ "string", "null" ], "description": "The router that picked the model, when one did (e.g. `auto`)." }, "service_tier": { "type": [ "string", "null" ] }, "data_region": { "type": [ "string", "null" ] }, "session_id": { "type": [ "string", "null" ] }, "run_id": { "type": [ "string", "null" ] }, "parent_request_id": { "type": [ "string", "null" ] }, "external_user": { "type": [ "string", "null" ], "description": "The `user` the caller sent, for its own attribution." }, "workspace_name": { "type": [ "string", "null" ] }, "key": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "prefix": { "type": "string" } }, "description": "The key that made the request, by name and visible prefix. Null once the key is deleted." }, "usage": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "US dollars." }, "cost": { "type": "number", "description": "US dollars." } } } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer" }, "model_id": { "type": "string" }, "provider_slug": { "type": "string" }, "endpoint_id": { "type": "string" }, "is_byok": { "type": "boolean" }, "status": { "enum": [ "ok", "error" ] }, "http_status": { "type": [ "integer", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "ttft_ms": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "feedback": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "label": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "value", "label", "updated_at" ] } } } } ] }, "GenerationFeedback": { "type": "object", "properties": { "id": { "type": "string", "description": "The generation id (`gen-…`)." }, "value": { "type": "number", "minimum": -1, "maximum": 1, "description": "From -1 to 1: thumbs down -1, thumbs up 1." }, "label": { "type": [ "string", "null" ], "description": "A slug such as `helpful`, or null." }, "yours": { "type": "boolean", "description": "Whether the calling key submitted this score. Which key did is never returned." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "value", "label", "yours", "created_at", "updated_at" ] }, "Org": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "members": { "type": "integer", "description": "Active seats." } }, "required": [ "id", "name", "slug", "plan", "created_at", "members" ] }, "Batch": { "type": "object", "properties": { "id": { "type": "string", "description": "`batch_…`" }, "object": { "enum": [ "batch" ] }, "endpoint": { "enum": [ "/v1/chat/completions" ] }, "model": { "type": "string", "description": "The `:batch` model." }, "provider": { "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed", "cancelled", "expired" ] }, "created_at": { "type": "integer" }, "completed_at": { "type": [ "integer", "null" ] }, "expires_at": { "type": "integer" }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" } } }, "errors": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, { "type": "null" } ] }, "generation_id": { "type": "string", "description": "The request id; `GET /v1/generation?id=` reads its cost." }, "usage": { "type": "object", "properties": { "cost": { "type": "number", "description": "US dollars." }, "is_byok": { "type": "boolean" } } } } }, "Video": { "type": "object", "properties": { "id": { "type": "string", "description": "`video_…`" }, "object": { "enum": [ "video" ] }, "model": { "type": "string" }, "provider": { "type": "string" }, "status": { "enum": [ "queued", "in_progress", "completed", "failed" ] }, "created_at": { "type": "integer" }, "completed_at": { "type": [ "integer", "null" ] }, "expires_at": { "type": "integer" }, "seconds": { "type": [ "number", "null" ] }, "error": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" } } }, { "type": "null" } ] }, "generation_id": { "type": "string", "description": "The request id; `GET /v1/generation?id=` reads it." }, "usage": { "type": "object", "properties": { "cost": { "type": "number", "description": "US dollars." }, "is_byok": { "type": "boolean" } } } } }, "FileObject": { "type": "object", "properties": { "id": { "type": "string", "description": "`file-…`" }, "object": { "enum": [ "file" ] }, "bytes": { "type": "integer" }, "created_at": { "type": "integer" }, "expires_at": { "type": "integer" }, "filename": { "type": "string" }, "purpose": { "type": "string" }, "mime_type": { "type": "string", "description": "What the bytes are, whatever the name says." }, "status": { "enum": [ "processed" ] } } }, "ClassifierConditions": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "string", "description": "A glob over the model the request named, e.g. `openai/*` or `@preset/*`." } }, "key_names": { "type": "array", "items": { "type": "string" } }, "workspace_ids": { "type": "array", "items": { "type": "string" } }, "agents": { "type": "array", "items": { "type": "string" } }, "apps": { "type": "array", "items": { "type": "string", "description": "The app's title or the referer's host." } }, "has_tools": { "type": "boolean" }, "has_images": { "type": "boolean" }, "stream": { "type": "boolean" }, "min_prompt_tokens": { "type": "integer" }, "max_prompt_tokens": { "type": "integer" } } }, "Classifier": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tag": { "type": "string" }, "priority": { "type": "integer" }, "conditions": { "$ref": "#/components/schemas/ClassifierConditions" }, "preset": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Connection": { "type": "object", "properties": { "kind": { "enum": [ "plugin", "mcp" ] }, "slug": { "type": "string", "description": "The plugin's slug, or the MCP server's name: what `include` and `exclude` take." }, "status": { "enum": [ "ok", "not_connected", "expired", "disabled", "unreachable" ] }, "tools_source": { "enum": [ "live", "manifest", "none" ], "description": "`live`: asked just now. `manifest`: the plugin's stored manifest, because it could not be asked." }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "As the model sees it: `plugin____` or `mcp____`. What `writes` takes." }, "tool": { "type": "string", "description": "The connection's own name for it." }, "description": { "type": [ "string", "null" ] }, "mode": { "enum": [ "read", "write" ] } } } } } }, "ServerTool": { "type": "object", "properties": { "type": { "type": "string", "description": "What a request puts in tools[].type, e.g. `autonomousrelay:datetime`." }, "group": { "enum": [ "web", "multi_model", "code", "files", "utilities" ] }, "third_party": { "type": "boolean", "description": "Running it sends request data to a third party." }, "available": { "type": "boolean", "description": "Built. A request declaring an unavailable tool is a 400 naming it." }, "enabled": { "type": "boolean" } } }, "Preset": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer" }, "body": { "type": "object", "properties": {} }, "reference": { "type": "string", "description": "What a request puts in `model`: `@preset/`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AgentDefinition": { "type": "object", "properties": { "slug": { "type": "string", "description": "Also the `X-Autonomous-Relay-Agent` tag every turn carries, so agent budgets apply." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "enum": [ "active", "paused", "archived" ] }, "version": { "type": "integer" }, "model": { "type": "string", "description": "A model id or `@preset/`." }, "tools": { "type": "array", "items": { "type": "object", "properties": {}, "required": [ "type" ] } }, "run_defaults": { "type": "object", "properties": { "budget_usd": { "type": "number" }, "max_turns": { "type": "integer" }, "max_tool_calls": { "type": "integer" }, "max_cost_per_minute_usd": { "type": "number" }, "max_tool_calls_without_progress": { "type": "integer" }, "model_policy": { "type": "object", "properties": {} } }, "required": [ "budget_usd", "max_turns", "max_tool_calls" ] }, "approval": { "type": "object", "properties": { "mode": { "enum": [ "writes", "all", "none" ], "description": "`writes` (the default) pauses the run before any tool that does not declare itself read-only (an MCP tool's `readOnlyHint`; the built-in tools only read); `all` before every server tool; `none` never." }, "expires_minutes": { "type": "integer", "minimum": 5, "maximum": 1440, "description": "How long a pending action waits for a decision; the run ends when it expires. Default 1440 (24 hours)." }, "never_ask": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Plugin or MCP tools that run without a person even though they write, as the model names them (`plugin__slack__post_message`). An Owner's explicit trust for low-stakes writes; never list one that moves money. Applies in `writes` and `all` modes." } } }, "output": { "type": "object", "properties": { "destination_id": { "type": [ "string", "null" ], "description": "A webhook or S3 broadcast destination of the organisation: each finished run's result is delivered there as an `agent.run.completed` envelope -- the answer itself, so this is the one broadcast that carries content." }, "schema": { "type": [ "object", "null" ], "description": "A JSON Schema (`\"type\": \"object\"`, at most 8 KB) the final answer must follow, sent as `response_format`; the envelope then carries `output_json`." } } }, "invoke": { "type": "string", "description": "The path that runs it." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AgentTurn": { "type": "object", "properties": { "agent": { "type": "string" }, "version": { "type": "integer" }, "status": { "enum": [ "completed", "awaiting_approval" ] }, "approval": { "type": "object", "properties": { "action_id": { "type": "string" }, "run_id": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" } } } }, "expires_at": { "type": "string", "format": "date-time" } } }, "decision": { "enum": [ "approved", "rejected" ], "description": "On a decision's answer only." }, "output": { "type": [ "string", "null" ] }, "finish_reason": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "generation_id": { "type": [ "string", "null" ] }, "usage": { "type": "object", "properties": {} }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "budget": { "type": "number", "description": "US dollars." }, "spent": { "type": "number", "description": "US dollars." }, "turns_used": { "type": "integer" }, "tool_calls_used": { "type": "integer" }, "definition_version": { "type": "integer" } } } } }, "AgentTrigger": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "enum": [ "webhook", "schedule", "plugin_event" ] }, "name": { "type": "string" }, "plugin": { "type": "string", "description": "plugin_event: the installed plugin's slug." }, "event_type": { "type": "string", "description": "plugin_event: the event its connector posts." }, "key_hash": { "type": "string", "description": "The inference key the runs are made as." }, "input_template": { "type": "string", "description": "The run's input: `{{path}}` placeholders filled from the delivery (`{{body}}` for all of it); on a schedule, from `fired_at` and `trigger`." }, "event_id_field": { "type": [ "string", "null" ], "description": "Webhook: where in the delivery the sender's event id is; a repeat within a day starts nothing." }, "every_minutes": { "type": [ "integer", "null" ], "description": "Schedule: every this many minutes, 5 to 10080." }, "next_fire_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_runs_per_hour": { "type": "integer" }, "max_concurrent": { "type": "integer" }, "status": { "enum": [ "active", "paused" ] }, "last_fired_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string", "description": "Webhook: the path deliveries are posted to." }, "created_at": { "type": "string", "format": "date-time" } } }, "PendingAction": { "type": "object", "properties": { "id": { "type": "string" }, "run_id": { "type": "string" }, "agent": { "type": [ "string", "null" ] }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "enum": [ "server", "mcp", "plugin" ] } } } }, "status": { "enum": [ "pending", "approved", "rejected", "expired" ] }, "note": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "decide": { "type": "string", "description": "The path that decides it." } } }, "PluginListing": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "publisher": { "type": "string" }, "official": { "type": "boolean", "description": "Built by Autonomous Relay: a platform organisation owns it." }, "built_by": { "type": "string", "description": "The name to show: Autonomous Relay when official, else the publisher." }, "homepage_url": { "type": [ "string", "null" ] }, "privacy_url": { "type": [ "string", "null" ] }, "auth": { "enum": [ "none", "api_key", "oauth2" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "icon_url": { "type": [ "string", "null" ], "description": "The logo, on this origin, or null when it has none." } } }, "PluginDetail": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "publisher": { "type": "string" }, "official": { "type": "boolean", "description": "Built by Autonomous Relay: a platform organisation owns it." }, "built_by": { "type": "string", "description": "The name to show: Autonomous Relay when official, else the publisher." }, "homepage_url": { "type": [ "string", "null" ] }, "privacy_url": { "type": [ "string", "null" ] }, "auth": { "enum": [ "none", "api_key", "oauth2" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "icon_url": { "type": [ "string", "null" ], "description": "The logo, on this origin, or null when it has none." }, "connector": { "type": [ "object", "null" ], "description": "What a connector says it does, from its manifest; null for a plain plugin.", "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "mode": { "enum": [ "read", "write" ], "description": "`write` tools wait for a person to approve them." } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } } } }, "data_residency": { "type": "array", "items": { "type": "object", "properties": { "what": { "type": "string" }, "region": { "type": "string" }, "retention": { "type": "string" } } } } } } } }, "Plugin": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "publisher": { "type": "string" }, "official": { "type": "boolean", "description": "Built by Autonomous Relay: a platform organisation owns it." }, "built_by": { "type": "string", "description": "The name to show: Autonomous Relay when official, else the publisher." }, "homepage_url": { "type": [ "string", "null" ] }, "privacy_url": { "type": [ "string", "null" ] }, "auth": { "enum": [ "none", "api_key", "oauth2" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "icon_url": { "type": [ "string", "null" ], "description": "The logo, on this origin, or null when it has none." }, "oauth_authorize_url": { "type": [ "string", "null" ] }, "oauth_token_url": { "type": [ "string", "null" ] }, "oauth_client_id": { "type": [ "string", "null" ] }, "oauth_scopes": { "type": [ "string", "null" ] }, "has_client_secret": { "type": "boolean" }, "mcp_url": { "type": "string" }, "auth_header": { "type": [ "string", "null" ] }, "status": { "enum": [ "private", "pending", "approved", "rejected", "suspended" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "PluginInput": { "type": "object", "properties": { "slug": { "type": "string", "description": "2-40 lowercase letters, digits or hyphens; fixed once created." }, "name": { "type": "string" }, "summary": { "type": "string", "description": "At most 280 characters." }, "description": { "type": [ "string", "null" ] }, "publisher": { "type": "string" }, "homepage_url": { "type": [ "string", "null" ] }, "privacy_url": { "type": [ "string", "null" ] }, "mcp_url": { "type": "string", "description": "Your MCP endpoint: public https, Streamable HTTP." }, "auth": { "enum": [ "none", "api_key", "oauth2" ] }, "oauth_authorize_url": { "type": "string", "description": "oauth2: your authorization endpoint (public https)." }, "oauth_token_url": { "type": "string", "description": "oauth2: your token endpoint (public https)." }, "oauth_client_id": { "type": "string", "description": "oauth2: the client id you issued us." }, "oauth_client_secret": { "type": "string", "description": "oauth2, confidential clients: write-only, sealed, never returned." }, "oauth_scopes": { "type": "string", "description": "oauth2: the scope string to request." }, "auth_header": { "type": "string", "description": "For api_key: the header the key is sent in. Default Authorization." }, "categories": { "type": "array", "items": { "enum": [ "productivity", "data", "developer", "search", "communication", "finance", "marketing", "sales", "support", "other" ] } }, "icon": { "type": [ "string", "null" ], "description": "The logo: `data:image/png;base64,...`, or JPEG, WebP or SVG, at most 64 KB decoded. An SVG may not carry scripts or event handlers. null removes it." } } }, "ConnectorManifest": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "mode": { "enum": [ "read", "write" ] }, "context": { "type": "array", "items": { "type": "string" } } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "context": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "array", "items": { "type": "string" } } } } }, "handshake_url": { "type": [ "string", "null" ] }, "uninstall_url": { "type": [ "string", "null" ], "description": "Told when an organisation removes the install, so the connector erases what it holds for it." }, "data_residency": { "type": "array", "items": { "type": "object", "properties": { "what": { "type": "string" }, "region": { "type": "string" }, "retention": { "type": "string" } } } } } }, "PluginInstall": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" }, "credential_hint": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "events_ready_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Connectors: when the install last received its events token." }, "handshake_error": { "type": [ "string", "null" ], "description": "Connectors: why the last handshake failed." }, "connected": { "type": "boolean", "description": "Whether it holds what it needs to run: an OAuth connection's tokens or a key. Always true for a plugin that takes neither." }, "connected_at": { "type": "string", "format": "date-time" }, "connected_by": { "type": [ "object", "null" ], "description": "Who connected it last; null when no person did, or they have left.", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": "string" } } }, "plugin": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "publisher": { "type": "string" }, "official": { "type": "boolean", "description": "Built by Autonomous Relay: a platform organisation owns it." }, "built_by": { "type": "string", "description": "The name to show: Autonomous Relay when official, else the publisher." }, "auth": { "type": "string" }, "status": { "type": "string" }, "icon_url": { "type": [ "string", "null" ] } } } } }, "McpServer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" } }, "header_name": { "type": [ "string", "null" ] }, "header_hint": { "type": [ "string", "null" ] }, "disabled": { "type": "boolean" }, "created_at": { "type": "string" } } }, "BroadcastDestination": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "enum": [ "webhook", "otlp", "s3", "langfuse", "datadog" ] }, "url": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "sample_rate": { "type": "number" }, "disabled": { "type": "boolean" }, "header_name": { "type": [ "string", "null" ] }, "header_hint": { "type": [ "string", "null" ] }, "s3_region": { "type": "string", "description": "s3 only." }, "s3_bucket": { "type": "string", "description": "s3 only." }, "s3_prefix": { "type": [ "string", "null" ], "description": "s3 only." }, "s3_path_style": { "type": "boolean", "description": "s3 only." }, "s3_access_key_id": { "type": "string", "description": "s3 only." }, "s3_secret_hint": { "type": "string", "description": "s3 only: the secret access key's last four characters. The key itself is never returned." }, "langfuse_public_key": { "type": "string", "description": "langfuse only: the project's public key." }, "langfuse_secret_hint": { "type": "string", "description": "langfuse only: the secret key's last four characters. The key itself is never returned." }, "datadog_site": { "type": "string", "description": "datadog only: the Datadog site, e.g. `datadoghq.eu`." }, "datadog_api_key_hint": { "type": "string", "description": "datadog only: the API key's last four characters. The key itself is never returned." }, "last_attempt_at": { "type": [ "string", "null" ] }, "last_success_at": { "type": [ "string", "null" ] }, "last_http_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "RoutingDefaultsInput": { "type": "object", "properties": { "default_model": { "type": [ "string", "null" ], "description": "A listed model id, used when a request names none." }, "fallback_models": { "type": "array", "items": { "type": "string", "description": "A listed model id. At most 8." } }, "default_sort": { "enum": [ "price", "throughput", "latency", null ], "description": "The provider sort when a request sets none." }, "lock_sort": { "type": "boolean", "description": "Ignore a request's own provider.sort. Needs default_sort." } } }, "RoutingDefaults": { "type": "object", "properties": { "default_model": { "type": [ "string", "null" ] }, "fallback_models": { "type": "array", "items": { "type": "string" } }, "default_sort": { "enum": [ "price", "throughput", "latency", null ] }, "lock_sort": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "default_model", "fallback_models", "default_sort", "lock_sort", "updated_at" ] }, "PrivacyPolicyInput": { "type": "object", "properties": { "zdr": { "type": "boolean", "description": "Removed. `false` is accepted; `true` is a 400." }, "zdr_groups": { "type": "array", "items": { "type": "string" }, "description": "Removed. An empty list is accepted; any group is a 400." }, "deny_training": { "type": "boolean", "description": "Removed. `false` is accepted; `true` is a 400." }, "regions": { "type": "array", "items": { "type": "string", "description": "A region an endpoint declares, e.g. `us`. Empty = unrestricted." } } } }, "PrivacyPolicy": { "type": "object", "properties": { "regions": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "regions", "updated_at" ] }, "Eligibility": { "type": "object", "properties": { "available": { "type": "integer" }, "unavailable": { "type": "integer" }, "excluded": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "unmet": { "type": "array", "items": { "enum": [ "region" ] } } } } } }, "required": [ "available", "unavailable", "excluded" ] }, "ActivityTotals": { "type": "object", "properties": { "requests": { "type": "integer" }, "errors": { "type": "integer", "description": "Requests that ended with an error code. Counted zero on deployments older than the reason codes, where no code was recorded." }, "byok_requests": { "type": "integer" }, "spend": { "type": "number", "description": "US dollars." }, "tokens": { "type": "integer", "description": "Prompt plus completion. `cache_read` and `reasoning` are subsets of those and are not added again." }, "prompt_tokens": { "type": "integer" }, "cached_tokens": { "type": "integer", "description": "Prompt tokens served from the provider's cache -- a subset of `prompt_tokens`." }, "cache_hit_rate": { "type": [ "number", "null" ], "description": "`cached_tokens / prompt_tokens`. Null when there were no prompt tokens, which is not the same as a rate of zero." }, "blended_per_million": { "type": [ "number", "null" ], "description": "USD per million tokens, blended across every model and provider in the window. Null when there were no tokens." } } }, "UpstreamRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque; the row's identity, not the request's." }, "request_id": { "type": "string", "description": "The generation this dispatch was made for. Several rows share it when a fallback fired." }, "created_at": { "type": "string", "format": "date-time" }, "attempt": { "type": "integer", "description": "1-indexed position in the cascade." }, "model_id": { "type": "string" }, "provider_slug": { "type": "string" }, "endpoint_id": { "type": "string" }, "is_byok": { "type": "boolean" }, "status": { "enum": [ "ok", "error" ], "description": "Whether the dispatch committed. A stream that shipped bytes and then failed is `ok` with an `error_message`." }, "http_status": { "type": [ "integer", "null" ], "description": "The upstream status. Null when the dispatch never reached the provider." }, "error_code": { "type": [ "string", "null" ], "description": "The provider's own code where the provider answered, or a `router.*` reason code where this gateway is what failed -- a credential it could not open, a request it could not express, a stream that broke after it had committed." }, "error_message": { "type": [ "string", "null" ], "description": "As on the request: the provider, status and code where the provider refused; never its own text." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Time inside the provider call. Null when nothing was dispatched." }, "ttft_ms": { "type": [ "integer", "null" ] } } }, "SessionSummary": { "type": "object", "properties": { "session_id": { "type": "string" }, "generations": { "type": "integer", "description": "Requests in this conversation, within the window." }, "errors": { "type": "integer" }, "started_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "spend": { "type": "number", "description": "US dollars." }, "tokens": { "type": "integer" }, "models": { "type": "array", "items": { "type": "string" }, "description": "Every model the conversation was served by. More than one means it switched mid-session." }, "providers": { "type": "array", "items": { "type": "string" } } } }, "Generation": { "type": "object", "properties": { "id": { "type": "string" }, "model": { "type": [ "string", "null" ], "description": "The model that served." }, "provider_name": { "type": [ "string", "null" ] }, "endpoint_id": { "type": [ "string", "null" ] }, "quantization": { "type": [ "string", "null" ] }, "total_cost": { "type": "number", "description": "US dollars." }, "finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", "content_filter", "error", null ], "description": "Normalized to five values. `native_finish_reason` carries the provider's own." }, "native_finish_reason": { "type": [ "string", "null" ] }, "streamed": { "type": "boolean" }, "cancelled": { "type": "boolean" }, "is_byok": { "type": "boolean" }, "latency": { "type": [ "integer", "null" ], "description": "Time to first token, in milliseconds." }, "generation_time": { "type": [ "integer", "null" ], "description": "Milliseconds." }, "price_version_ids": { "type": "array", "items": { "type": "integer" } }, "usage_lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number" }, "cost_nanodollars": { "type": "string", "description": "Nanodollars (1e-9 USD), an integer as a string." }, "price_version_id": { "type": [ "integer", "null" ] }, "price_override": { "type": [ "integer", "null" ], "description": "Which of that price row's conditional prices (`pricing.overrides[]`) priced this line, by position; null when its own price did." } } } }, "app_id": { "type": [ "string", "null" ] }, "app_title": { "type": [ "string", "null" ] }, "http_referer": { "type": [ "string", "null" ], "description": "Scheme and host only. The path, query string and fragment are never stored on a request, because that is where an app puts the user it is serving." }, "user_agent": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Credits": { "type": "object", "properties": { "total_credits": { "type": "number", "description": "US dollars." }, "held_credits": { "type": "number", "description": "US dollars." }, "available_credits": { "type": "number", "description": "US dollars." }, "credit_line": { "type": "number", "description": "US dollars." } } }, "CreditPurchase": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "provider": { "type": "string" }, "status": { "type": "string" }, "gross": { "type": "number", "description": "US dollars." }, "fee": { "type": "number", "description": "US dollars." }, "net": { "type": "number", "description": "US dollars." }, "tax_jurisdiction": { "type": [ "string", "null" ] }, "has_document": { "type": "boolean" } } }, "ByokCredential": { "type": "object", "properties": { "id": { "type": "string" }, "provider_slug": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "key_hint": { "type": "string", "description": "The last characters of the key. The key itself is never returned." }, "tier": { "enum": [ "prioritized", "fallback" ] }, "priority": { "type": "integer" }, "fallback_policy": { "enum": [ "platform", "none_for_models", "none_for_provider" ] }, "model_filter": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } } }, "allowed_models": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string" }, "description": "Model ids or `*` patterns, ANDed with `model_filter`." }, "allowed_api_key_hashes": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "Only these API keys (their `hash`, as `GET /v1/keys` lists it) may use the credential." }, "allowed_user_ids": { "type": [ "array", "null" ], "maxItems": 100, "minItems": 1, "items": { "type": "string", "format": "uuid" }, "description": "Only keys these members are behind -- created, or signed in with -- may use the credential. A key no person is behind is outside the list." }, "disabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ContentLoggingSettings": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "§13.1: off by default. Cannot be set true in this release — gated on the review of `PIA-2026-001`." }, "key_include": { "type": "array", "items": { "type": "string" }, "description": "Key hashes to capture. Empty means every key." }, "key_exclude": { "type": "array", "items": { "type": "string" }, "description": "**Exclusion wins** over inclusion — a key in both is not captured." }, "retention_days": { "type": "integer", "description": "At least 90 (§13.1's ~3-month floor). Content past this is deleted hourly." }, "locked": { "type": "boolean", "description": "Settings frozen; further changes refused until cleared." }, "purposes": { "type": "array", "items": { "enum": [ "self_access", "rag" ] }, "description": "What this organisation consented to. `self_access` is its own replay and debugging; `rag` would be indexing, and is a separate grant because consent is purpose-specific." }, "consented_at": { "type": [ "string", "null" ], "description": "When logging was enabled. Null while it is off." } }, "required": [ "enabled", "key_include", "key_exclude", "retention_days", "locked", "purposes" ] }, "Guardrail": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "model_allowlist": { "type": "array", "items": { "type": "string" } }, "provider_allowlist": { "type": "array", "items": { "type": "string" } }, "allowed_data_regions": { "type": "array", "items": { "type": "string" }, "description": "Regions an endpoint may run in, matched exactly against the endpoint `deployment_region` field and lower-cased on write. Empty is unrestricted. This fails CLOSED: an endpoint that declares no region is not in one, so it is refused. A region no ready endpoint declares is rejected at write time rather than refusing every request later." }, "budget_nanodollars": { "type": [ "string", "null" ], "description": "Nanodollars (1e-9 USD), an integer as a string." }, "budget_reset": { "type": [ "string", "null" ] }, "include_byok_spend": { "type": "boolean", "description": "Count spend made on your own provider credential toward this ceiling, at IMPUTED LIST PRICE -- what the call would have cost on platform capacity, not the platform fee charged. Defaults to true: every model is BYOK-only, so a ceiling that skipped this spend would count nothing and could never bind. Set false to count only platform spend." }, "content_filter_builtins": { "type": "array", "items": { "type": "string" } }, "content_filters": { "type": "array", "items": { "$ref": "#/components/schemas/ContentFilter" } }, "filter_allowlist": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "subject_type": { "type": "string" }, "subject_id": { "type": "string" } } } } }, "additionalProperties": true, "description": "The stored row. **Its field names are the database's, and differ from the create body's** -- `model_allowlist` here is `allowed_models` there." }, "ContentFilter": { "type": "object", "properties": { "pattern": { "type": "string", "description": "A regular expression. One that could backtrack catastrophically is refused." }, "action": { "enum": [ "flag", "redact", "block" ] }, "label": { "type": "string" } }, "required": [ "pattern", "action", "label" ] }, "WorkspaceBudget": { "type": "object", "properties": { "interval": { "enum": [ "daily", "weekly", "monthly", "lifetime" ] }, "limit_nanodollars": { "type": "string", "description": "Nanodollars (1e-9 USD), an integer as a string." }, "include_byok": { "type": "boolean", "description": "Count spend made on your own provider credential toward this ceiling, at IMPUTED LIST PRICE -- what the call would have cost on platform capacity, not the platform fee charged. Defaults to true: every model is BYOK-only, so a ceiling that skipped this spend would count nothing and could never bind. Set false to count only platform spend." } } }, "Run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "enum": [ "open", "paused", "completed", "exhausted", "cancelled" ], "description": "`exhausted` is set by settlement when spend reaches the budget, and `paused` by the §17.4 runaway detector. A caller may set only `completed` or `cancelled` — a client able to claim either of the other two could report a breach that never happened.\n\n`paused` is the one non-open status that is **recoverable**: see `POST /v1/runs/{id}/resume`." }, "goal": { "type": [ "string", "null" ] }, "budget": { "type": "number", "description": "The ceiling. Required at creation, always positive: a run without one is what §17.1 exists to prevent." }, "spent": { "type": "number", "description": "Settled. **Imputed list price** — what the turns were worth at catalog prices, not money billed through us. Under the BYOK-only policy inference is billed by your own provider, and a run sized on our fee would report every turn as free (§9.6)." }, "reserved": { "type": "number", "description": "Worst-case imputed cost committed by turns admitted but not yet settled. Published because `budget - spent` alone overstates the headroom a run actually has." }, "remaining": { "type": "number", "description": "`budget - spent - reserved`." }, "max_turns": { "type": [ "integer", "null" ] }, "turns_used": { "type": "integer" }, "max_tool_calls": { "type": [ "integer", "null" ] }, "tool_calls_used": { "type": "integer" }, "model_policy": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } } }, "max_cost_per_minute": { "type": [ "number", "null" ], "description": "§17.4 threshold, in USD. Null means the cost-velocity detector is off for this run." }, "max_tool_calls_without_progress": { "type": [ "integer", "null" ], "description": "§17.4 threshold. Null means the no-progress detector is off for this run." }, "tool_calls_without_progress": { "type": "integer", "description": "Consecutive tool calls with no answering turn between them. Reset to 0 by any turn finishing with something other than `tool_calls`." }, "pause_reason": { "type": [ "string", "null" ], "enum": [ "cost_velocity", "no_progress", null ], "description": "Which detector paused this run. Set only by settlement — the actionable half, since a paused run without a stated cause leaves you guessing which threshold to raise." }, "paused_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "budget", "spent", "reserved", "remaining", "turns_used", "tool_calls_used" ] }, "RunTurn": { "type": "object", "properties": { "id": { "type": "string", "description": "The generation id — the same id `/v1/generation` takes." }, "created_at": { "type": "string", "format": "date-time" }, "session_id": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ], "description": "What actually served. Null when no candidate was reached." }, "provider": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`pending`, `complete` or `failed`." }, "finish_reason": { "type": [ "string", "null" ] }, "cost": { "type": "number", "description": "US dollars." }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "cached_tokens": { "type": "integer", "description": "Included in `prompt_tokens`, not additional to it." }, "tool_calls": { "type": "integer" }, "failed_tool_calls": { "type": "integer" }, "ttft_ms": { "type": [ "integer", "null" ] }, "generation_ms": { "type": [ "integer", "null" ] }, "routing_overhead_ms": { "type": [ "integer", "null" ] }, "is_byok": { "type": "boolean" } }, "required": [ "id", "created_at", "cost" ] }, "RunTree": { "allOf": [ { "$ref": "#/components/schemas/Run" }, { "type": "object", "properties": { "turn_count": { "type": "integer" }, "truncated": { "type": "boolean", "description": "The turn list hit its 500-row cap. Use `/v1/activity` for bulk reading." }, "cache_hit_rate": { "type": [ "number", "null" ], "description": "`cache_read` over `prompt` tokens. **Null, never 0**, when nothing has been metered: a run that has not billed has no hit rate, and 0% would read as a cache that is working and missing." }, "model_switches": { "type": "integer", "description": "Transitions between consecutive turns, skipping turns that never reached a provider." }, "failed_tool_calls": { "type": "integer" }, "turns": { "type": "array", "items": { "$ref": "#/components/schemas/RunTurn" } } }, "required": [ "turn_count", "turns" ] } ] }, "AuthorizeInfo": { "type": "object", "properties": { "callback_url": { "type": [ "string", "null" ], "description": "Where the code will be returned. Null for the headless flow." }, "host": { "type": [ "string", "null" ], "description": "The callback's host — what the consent screen puts in front of the user. Null when headless, and then `key_label` is the only name there is." }, "headless": { "type": "boolean", "description": "No callback URL: the code is displayed for manual entry. Requires `S256` and `key_label`." }, "key_label": { "type": "string", "description": "Names the issued key on the Keys screen, so access can be revoked by app." }, "code_challenge_method": { "enum": [ "S256" ], "description": "Always `S256`; `plain` and `none` are refused for every flow." }, "limit": { "type": "number", "description": "The spend ceiling the issued key will carry. Served rather than hardcoded in the consent screen, so the terms shown are the terms applied." }, "expires_in_days": { "type": "integer", "description": "How long the issued key will last." } }, "required": [ "callback_url", "host", "headless", "key_label", "code_challenge_method", "limit", "expires_in_days" ] }, "OAuthGrant": { "type": "object", "properties": { "code": { "type": "string", "description": "The one-time code. Ten minutes, single use." }, "redirect_to": { "type": [ "string", "null" ], "description": "The callback URL with `code` appended, preserving any query the app already put there. Null when headless." }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "redirect_to", "expires_at" ] }, "OAuthKey": { "type": "object", "properties": { "key": { "type": "string", "description": "The inference key. In this response and never again — only a salted hash is stored." }, "hash": { "type": "string", "description": "Identifies the key for revocation." }, "label": { "type": "string", "description": "The app this key was issued to." }, "limit": { "type": [ "number", "null" ], "description": "The spend ceiling, in US dollars." }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "key", "hash", "label", "limit", "expires_at" ] }, "Session": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time" }, "org_id": { "type": "string", "format": "uuid" }, "key_name": { "type": [ "string", "null" ] }, "user": { "anyOf": [ { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "provider": { "type": "string" } } }, { "type": "null" } ] }, "auth_method": { "type": "string" }, "super_admin": { "type": "boolean", "description": "This person is a super admin (Tech Service 4U staff: a verified email on a SUPER_ADMIN_DOMAINS domain, Owner or Admin of the platform organisation, signed in to the dashboard)." }, "org_suspended": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } } }, { "type": "null" } ], "description": "Set while a super admin has suspended this organisation: every request is refused with 403 `org_suspended`." } } }, "Health": { "type": "object", "properties": { "status": { "const": "ok" }, "version": { "type": "string", "description": "The same value this document publishes as `info.version`." }, "rate_limiting": { "type": "object", "properties": { "backend": { "enum": [ "redis", "redis-degraded", "memory" ], "description": "`redis-degraded`: Redis was reachable at boot and is not answering now; counts are per instance until it is." }, "sharedAcrossInstances": { "type": "boolean", "description": "False means each instance limits alone: N instances, N times the limit." }, "degradedSince": { "type": "string", "format": "date-time", "description": "Present only while `redis-degraded`: when the outage began." } } } }, "required": [ "status" ] }, "HealthDiagnostics": { "type": "object", "properties": { "status": { "const": "ok" }, "version": { "type": "string" }, "rate_limiting": { "type": "object", "properties": { "backend": { "enum": [ "redis", "redis-degraded", "memory" ] }, "sharedAcrossInstances": { "type": "boolean" }, "degradedSince": { "type": "string", "format": "date-time" } } }, "caches": { "type": "object", "additionalProperties": true, "description": "Hit, miss, stale and size counters for the hot-path caches (`auth`, `guardrails`, `budgets`, `byok`, `catalog`). Authenticated because the first four move with real account activity: served publicly they were a side channel anyone could poll." }, "endpoint_health_age_ms": { "type": [ "integer", "null" ], "description": "Age of the routing health snapshot. Growing without bound means the refresher has died and routing is deciding on stale tiers — which looks exactly like healthy routing." } }, "required": [ "status" ] }, "RoutePreviewRequest": { "type": "object", "properties": { "model": { "type": "string", "description": "The model to route, exactly as `/v1/chat/completions` takes it -- `:free`, `:nitro`, `:floor`, `:exacto` suffixes and `~author/family-latest` aliases included." }, "models": { "type": "array", "items": { "type": "string" }, "description": "A fallback chain, previewed in order. Walked to the same depth a real request would walk it." }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" }, "tools": { "type": "array", "items": { "type": "object" }, "description": "Only the COUNT matters here: a non-empty list makes `tools` a required parameter, which is a hard filter under `require_parameters`." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "description": "Optional. Supplied only so content filters and the sticky prefix hash can be evaluated; nothing is sent to a provider. Omit them and `content_filter` comes back null rather than a fabricated `allow`." }, "session_id": { "type": "string", "description": "Sticky-routing key, as on the chat route." }, "prompt_cache_key": { "type": "string" }, "routing_stability": { "enum": [ "adaptive", "sticky", "pinned" ] }, "routing_seed": { "type": "string", "description": "Seeds the weighted draw so a preview is reproducible and quotable in a bug report. Named `routing_seed`, not `seed`: the latter is OpenAI's sampling seed on the chat route, and one name for two knobs on sibling endpoints is a trap." } } }, "RoutePreviewCandidate": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "endpoint_id": { "type": "string" }, "quantization": { "type": "string" }, "context_length": { "type": "integer" }, "is_byok": { "type": "boolean" }, "byok_credential_id": { "type": [ "string", "null" ], "description": "Which credential routing chose. The key itself and its hint never appear here." }, "byok_tier": { "type": [ "string", "null" ], "description": "`prioritized` or `fallback` — FR-BYOK-3 ordering." }, "tier": { "type": "string", "description": "§8.2 health tier: `unrated`, `normal`, `degraded` or `fallback-only`." }, "price_score_nanodollars": { "type": "number", "description": "The blended prompt+completion price the ranking weights by, in nanodollars per token. Exact, because it is the figure the router itself read — this endpoint publishes no cost *estimate*." } }, "required": [ "model", "provider", "endpoint_id", "is_byok" ] }, "RoutePreview": { "type": "object", "properties": { "requested": { "type": "string" }, "strategy": { "type": "string", "description": "`direct`, `fallback` for a `models[]` chain, or `latest` for a `~alias`." }, "would_dispatch": { "type": "boolean", "description": "Whether a real request with this body would reach a provider at all." }, "limit_warning": { "type": [ "string", "null" ], "description": "Set when the key is at or past a SOFT ceiling: the request would be served, with this sentence in its `x-autonomous-relay-limit-warning` header." }, "refusal": { "anyOf": [ { "type": "object", "properties": { "stage": { "enum": [ "budget", "content_filter", "routing" ] }, "message": { "type": "string" } }, "required": [ "stage", "message" ] }, { "type": "null" } ], "description": "Why not, in the order the pipeline refuses: a budget binds before a filter runs, and both before routing is consulted. Null when `would_dispatch` is true." }, "ordering": { "enum": [ "deterministic", "sampled" ], "description": "Whether `cascade` is **the** order or **one draw** from it.\n\n§8.9.1's default ranking is a weighted random shuffle, deliberately: a deterministic cheapest-first router starves every provider but one. So `sampled` means the real request draws again and may order the platform attempts differently — reproduce this draw with the same `routing_seed`. `deterministic` means the order is fixed (an explicit `sort`, a `:floor`/`:nitro` variant, or too few platform attempts to shuffle) and a real request will match it." }, "routing_seed": { "type": "string", "description": "The seed this preview actually used, echoed so an unseeded call is still reproducible." }, "winner": { "anyOf": [ { "$ref": "#/components/schemas/RoutePreviewCandidate" }, { "type": "null" } ] }, "cascade": { "type": "array", "items": { "$ref": "#/components/schemas/RoutePreviewCandidate" }, "description": "The endpoints a real request would try, in order, after the sticky hoist and cut to the same fallback depth." }, "beyond_fallback_depth": { "type": "integer", "description": "Endpoints that survived every filter but sit past the fallback depth: eligible, and still unreachable." }, "endpoints": { "type": "object", "properties": { "total_before_filter": { "type": "integer", "description": "How many existed before filtering. \"3 exist, 1 eligible\" is the useful answer; \"1 of 1\" hides that two were excluded by your own policy." }, "eligible": { "type": "integer" } } }, "refused": { "type": "array", "items": { "type": "object", "properties": { "endpoint_id": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "code": { "type": "string", "description": "A stable machine code — `byok_required`, `guardrail_models`, `region`… — safe to branch on, unlike the prose beside it." }, "detail": { "type": "string", "description": "The human sentence, identical to the matching `unsatisfied_filters` entry." } }, "required": [ "endpoint_id", "code", "detail" ] }, "description": "One entry per excluded endpoint, carrying the FIRST constraint that removed it. `unsatisfied_filters` says which constraints emptied the set; this says which endpoints each one cost you." }, "unsatisfied_filters": { "type": "array", "items": { "type": "string" }, "description": "The same strings §7.7's 404 would carry." }, "unresolved_models": { "type": "array", "items": { "type": "string" }, "description": "Slugs in the chain that named no model we have — a typo, or a model since withdrawn." }, "guardrails": { "type": "object", "properties": { "applied": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "After §4.2 intersection: what actually binds, not what each level asked for. Empty means unrestricted." }, "allowed_providers": { "type": "array", "items": { "type": "string" } } } }, "content_filter": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } } }, "required": [ "action", "labels" ] }, { "type": "null" } ], "description": "Null when no `messages` were supplied. `labels` name the detectors that matched; the matched text never travels." }, "sticky": { "type": "object", "properties": { "stability": { "enum": [ "adaptive", "sticky", "pinned" ] }, "pin_source": { "type": [ "string", "null" ] }, "pinned_endpoint_id": { "type": [ "string", "null" ], "description": "The pin as it stands. Reading it here never writes or refreshes it." }, "hit": { "type": "boolean" }, "miss_reason": { "type": [ "string", "null" ] } } } }, "required": [ "requested", "would_dispatch", "cascade" ] } } } }