{ "openapi": "3.1.0", "info": { "title": "Anyray Gateway API", "version": "1.10.83", "summary": "OpenAI-compatible inference gateway that cuts the AI-inference spend your employees generate.", "description": "OpenAI-compatible inference API plus the coding-tool `/connect/*` API and the admin-gated console API (`/admin/*`) served by the Anyray gateway. Content-free by invariant: spend and request logs carry metadata only (user, team, model, provider, tokens, cost, latency, decision) — never prompt/response bodies. Opaque passthrough routes (the `/v1/*` proxy catch-alls, `/v1/copilot/*`, `/v1/proxy/*`) and the `/v1/realtime` WebSocket upgrade are intentionally omitted — a fixed schema would misrepresent them.", "contact": { "name": "Anyray", "url": "https://docs.anyray.ai" }, "license": { "name": "Documentation", "url": "https://docs.anyray.ai" } }, "externalDocs": { "description": "Anyray documentation", "url": "https://docs.anyray.ai/developers/api-reference" }, "servers": [ { "url": "https://{gatewayHost}", "description": "Your self-hosted Anyray gateway", "variables": { "gatewayHost": { "default": "localhost:8787", "description": "Host:port where your Anyray gateway is reachable. Defaults to :8787; put it behind TLS for any networked deployment." } } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "tags": [ { "name": "Chat", "description": "OpenAI-compatible chat and text completions." }, { "name": "Embeddings", "description": "OpenAI-compatible embeddings." }, { "name": "Messages", "description": "Anthropic-native Messages API." }, { "name": "Models", "description": "List the models the gateway can route to." }, { "name": "Audio", "description": "OpenAI-compatible speech, transcription, and translation." }, { "name": "Images", "description": "OpenAI-compatible image generation and edits." }, { "name": "Files", "description": "OpenAI-compatible file upload/retrieval for batch/fine-tune jobs." }, { "name": "Batches", "description": "OpenAI-compatible batch job lifecycle." }, { "name": "Responses", "description": "OpenAI-compatible Responses API." }, { "name": "Admin · Spend & governance", "description": "Content-free spend visibility and per-user token caps. Metadata only — never prompt/response content." }, { "name": "Admin · Health & settings", "description": "Liveness, runtime settings, self-updater, and the console auth handshake." }, { "name": "Admin · Optimizer, pricing & routing", "description": "Optimizer pipeline, price table, model aliases, routing, and the playground." }, { "name": "Admin · Providers", "description": "Server-held provider API keys (values never returned)." }, { "name": "Admin · Access, SSO & enrollment", "description": "SSO/IdP config, console login, client keys, enrollment links, provisioning tokens." }, { "name": "Admin · Privacy, support & observability", "description": "GDPR export/erase, support bundles, trace reads, onboarding." }, { "name": "Connect · Coding-tool integration", "description": "Endpoints the `anyray-connect` CLI and its PostToolUse hook call: team policy, per-developer savings, source-side output optimization, CCR retrieval, semantic recall, and dev-cert verification. Content-free — metadata and content-free handles only." }, { "name": "Connect · SSO enrollment", "description": "Pre-key browser SSO handshake used by `anyray-connect login`. Start is IP rate-limited; poll is authorized by a separate high-entropy secret stored only as a salted hash." } ], "paths": { "/v1/chat/completions": { "post": { "operationId": "createChatCompletion", "tags": ["Chat"], "summary": "Create a chat completion", "description": "OpenAI-compatible chat completion. The gateway selects the upstream provider (from the `x-anyray-provider` header, the request's routing config, or the configured default), injects the server-held provider key, runs the optimizer as a fail-open before-request hook, calls the provider, and meters the result content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "$ref": "#/components/parameters/ConfigHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "A chat completion. When `stream` is `true`, the body is a `text/event-stream` of `chat.completion.chunk` events terminated by `data: [DONE]`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "402": { "$ref": "#/components/responses/ServiceKeyBudgetExceeded" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/extensions/vscode/optimize": { "post": { "operationId": "optimizeVscodeLanguageModelRequest", "tags": ["Connect · Coding-tool integration"], "summary": "Optimize a VS Code language-model request", "description": "Authenticated pre-call hook for the official Anyray VS Code language-model provider. It applies the fail-open optimizer to the request and returns the resulting request to the extension, which then invokes the developer's selected VS Code/Copilot subscription model locally. The gateway does not choose or call an upstream provider, cannot short-circuit the request, and does not accept client-authored usage or cost. Prompt content is handled under the deployment's `ANYRAY_CONTENT_MODE`; spend and request logs remain metadata-only.", "parameters": [ { "$ref": "#/components/parameters/MetadataHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request": { "type": "object", "additionalProperties": true, "description": "The VS Code language-model request to optimize." } }, "required": ["request"] } } } }, "responses": { "200": { "description": "The request to pass to the selected VS Code model plus a bounded, content-free optimization summary.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request": { "type": "object", "additionalProperties": true }, "optimization": { "type": "object", "additionalProperties": false, "properties": { "optimizationId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "status": { "type": "string", "enum": [ "applied", "skipped", "disabled", "timeout", "error" ] }, "latencyMs": { "type": "integer", "minimum": 0, "maximum": 2000000000 }, "decisions": { "type": "array", "maxItems": 64, "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "estimatedTokensSaved": { "type": "integer", "minimum": 0, "maximum": 2000000000 } }, "required": ["kind"] } }, "estimatedTokensSaved": { "type": "integer", "minimum": 0, "maximum": 2000000000 } } } }, "required": ["request", "optimization"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/completions": { "post": { "operationId": "createCompletion", "tags": ["Chat"], "summary": "Create a (legacy) text completion", "description": "OpenAI-compatible legacy text completion. Prefer `/v1/chat/completions` for new work.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["model", "prompt"], "properties": { "model": { "type": "string", "minLength": 1, "description": "Model id or alias." }, "prompt": { "description": "The prompt(s) to complete.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "max_tokens": { "type": "integer", "minimum": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "stream": { "type": "boolean", "default": false } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "A text completion.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "402": { "$ref": "#/components/responses/ServiceKeyBudgetExceeded" } } } }, "/v1/embeddings": { "post": { "operationId": "createEmbedding", "tags": ["Embeddings"], "summary": "Create embeddings", "description": "OpenAI-compatible embeddings. Returns a vector per input.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" } } } }, "responses": { "200": { "description": "The embedding vectors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "402": { "$ref": "#/components/responses/ServiceKeyBudgetExceeded" } } } }, "/v1/messages": { "post": { "operationId": "createMessage", "tags": ["Messages"], "summary": "Create a message (Anthropic-native)", "description": "Anthropic-native Messages API. Point the Anthropic SDK's base URL at the gateway and it routes Claude requests through the same governance and optimization pipeline as the OpenAI-compatible endpoints.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" } } } }, "responses": { "200": { "description": "A message. When `stream` is `true`, the body is a `text/event-stream` of Anthropic message events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "402": { "$ref": "#/components/responses/ServiceKeyBudgetExceeded" } } } }, "/v1/messages/count_tokens": { "post": { "operationId": "countMessageTokens", "tags": ["Messages"], "summary": "Count tokens for a Messages request", "description": "Returns the input token count for an Anthropic-native Messages request without running inference.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" } } } }, "responses": { "200": { "description": "The input token count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/models": { "get": { "operationId": "listModels", "tags": ["Models"], "summary": "List models", "description": "Lists the models the gateway can route to, in the OpenAI `list` envelope.", "responses": { "200": { "description": "The available models.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } } } } }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/admin/spend/usage": { "get": { "tags": ["Admin · Spend & governance"], "summary": "Per-user usage detail", "description": "Per-user usage over a window with per-model and per-UTC-day breakdowns, each capped user's gauge, and an org-wide per-model rollup. Content-free.", "operationId": "adminSpendUsage", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mtd", "prev-month", "24h", "7d", "30d", "90d"], "default": "mtd" }, "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 200 }, "description": "Max users returned, heaviest first. `truncated` in the response flags when users were dropped." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendUsage" } } } } } } }, "/admin/spend/usage/properties": { "get": { "tags": [ "Admin · Spend & governance" ], "summary": "Spend grouped by a custom attribution dimension", "description": "Groups content-free spend over a window by one caller-supplied custom attribution dimension (sent as an `x-anyray-property-` request header, stored under `attribution.properties`). Returns per-value request, token, and cost totals. Content-free: attribution ids, counts, and USD only.", "operationId": "adminSpendUsageProperties", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "description": "The custom dimension name to group by (e.g. `feature`). Must match the bounded attribution-property charset." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mtd", "prev-month", "24h", "7d", "30d", "90d" ], "default": "mtd" }, "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "property": { "type": "string" }, "window": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "requests": { "type": "number" }, "totalTokens": { "type": "number" }, "costUsd": { "type": "number" } } } } } } } } } } } }, "/admin/spend-connectors": { "get": { "tags": ["Admin · Spend & governance"], "summary": "Read external spend connectors", "description": "Returns redacted configuration and optional poll status for the official Cursor, Devin, and GitHub Copilot usage connectors. Credentials are write-only and never appear in this response. Requires the `config:read` capability and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.", "operationId": "adminGetSpendConnectors", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "Redacted connector configuration. An unconfigured deployment returns an empty object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendConnectorsRead" } } } }, "401": { "description": "Admin authentication is required." }, "403": { "description": "The principal lacks `config:read` or is not the deployment owner." }, "500": { "description": "Connector state could not be read. The response does not expose credentials, ciphertext, or database details." } } }, "put": { "tags": ["Admin · Spend & governance"], "summary": "Set external spend connectors", "description": "Partially configure, rotate, or remove official vendor usage connectors. Omitted connectors stay unchanged; a connector object replaces that connector; `null` or `{}` removes it. Credential fields are write-only, encrypted at rest, never returned, and never audit-logged. Requires `providerkeys:manage` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.", "operationId": "adminPutSpendConnectors", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendConnectorsPatch" } } } }, "responses": { "200": { "description": "The resulting redacted connector configuration. Credential values are never echoed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendConnectorsRead" } } } }, "400": { "description": "Invalid JSON or connector configuration." }, "401": { "description": "Admin authentication is required." }, "403": { "description": "The principal lacks `providerkeys:manage` or is not the deployment owner." }, "500": { "description": "The encrypted configuration could not be persisted. The response does not expose credential or storage details." } } } }, "/admin/spend-connectors/sync": { "post": { "tags": ["Admin · Spend & governance"], "summary": "Synchronize external spend connectors", "description": "Requests a fleet-safe sync of every configured vendor connector. A durable lease prevents duplicate polling across replicas. Per-connector failures are isolated and represented only as `failed: true`; vendor bodies, signed report URLs, and credential-bearing errors are never returned. Requires `providerkeys:manage` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.", "operationId": "adminSyncSpendConnectors", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "Safe, content-free result for each configured connector.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendConnectorSyncResponse" } } } }, "401": { "description": "Admin authentication is required." }, "403": { "description": "The principal lacks `providerkeys:manage` or is not the deployment owner." }, "502": { "description": "The sync could not be started. The response contains only the fixed safe error message." } } } }, "/admin/spend-connectors/usage": { "get": { "tags": ["Admin · Spend & governance"], "summary": "Read external subscription usage", "description": "Aggregates imported, content-free usage while preserving vendor-native units: Cursor token/cost events, Devin ACUs, and GitHub Copilot credits/activity plus real CLI tokens. Copilot's published $0.01-per-credit list value is reported separately and is not an invoice total; ACUs and credits are never fabricated as tokens. Requires `config:read` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.", "operationId": "adminGetSpendConnectorUsage", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 }, "description": "Rolling lookback in days. Missing, non-integer, or out-of-range values use 30 days." } ], "responses": { "200": { "description": "Vendor-native usage totals over the requested window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendConnectorUsage" } } } }, "401": { "description": "Admin authentication is required." }, "403": { "description": "The principal lacks `config:read` or is not the deployment owner." }, "500": { "description": "Usage could not be read. The response does not expose database details." } } } }, "/admin/auth-events": { "get": { "tags": ["Admin · Spend & governance"], "summary": "Auth rejection diagnostics", "description": "Customer-local, content-free auth rejection events with machine-readable reason codes and remediation hints.", "operationId": "adminAuthEvents", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "user", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Optional customer-local user id filter." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Max events returned, newest first. Values above 200 are clamped." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEvents" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/admin/metering/last-report": { "get": { "tags": ["Admin · Health & settings"], "summary": "Read the last metering report", "description": "Returns the exact final payload from this process's last successful, verified metering round, plus the active diagnostics tier and metering state. Requires the `config:read` capability.", "operationId": "adminLastMeterReport", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/admin/user-caps": { "get": { "tags": ["Admin · Spend & governance"], "summary": "Get per-user caps + monthly usage", "description": "Caps, the org-wide cap-alert posture (webhook URL never returned — only whether configured), and current-month tokens per user.", "operationId": "adminGetUserCaps", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCapsGet" } } } } } }, "put": { "tags": ["Admin · Spend & governance"], "summary": "Set per-user caps + alert settings", "description": "Replace the caps map and (optionally) the cap-alert settings. Requires the `usercaps:write` capability. Webhook URL merge: absent=keep, null=clear, string=set.", "operationId": "adminSetUserCaps", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCapsPut" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCapsGet" } } } }, "400": { "description": "Invalid body (Zod validation)." } } } }, "/admin/spend": { "get": { "tags": ["Admin · Spend & governance"], "summary": "Spend summary (byUser)", "description": "In-memory content-free summary: requests + tokens per attributed user.", "operationId": "adminSpendSummary", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/spend/dashboard": { "get": { "tags": ["Admin · Spend & governance"], "summary": "Windowed spend dashboard", "description": "Money/usage split by billing class, per-day trend, top token-saving strategies, latency, and prompt-cache economics. Content-free.", "operationId": "adminSpendDashboard", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mtd", "prev-month", "24h", "7d", "30d", "90d"], "default": "mtd" }, "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/spend/quality-parity": { "get": { "tags": ["Admin · Spend & governance"], "summary": "Holdout quality-parity", "description": "Outcome proxies (turns/session, output tokens/request, error rate, latency) compared holdout vs treated, with 95% CIs and a verdict.", "operationId": "adminQualityParity", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mtd", "prev-month", "24h", "7d", "30d", "90d"], "default": "mtd" }, "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/health": { "get": { "tags": ["Admin · Health & settings"], "summary": "Health & schema version", "description": "Liveness, spend-store ping, and the applied vs expected DB schema version. Requires the `config:read` capability.", "operationId": "adminHealth", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/me": { "get": { "tags": ["Admin · Health & settings"], "summary": "Caller identity", "description": "The authenticated caller's identity and whether it may access deployment-global configuration. No capability required (any valid admin session). In fleet mode, `deploymentOwner` is false for every tenant-bound SSO principal regardless of tenant role.", "operationId": "adminMe", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "viewer", "auditor", "operator", "security_admin", "owner" ] }, "sub": { "type": "string" }, "kind": { "type": "string", "enum": ["token", "local", "sso"] }, "tenantId": { "type": "string" }, "deploymentOwner": { "type": "boolean", "description": "Whether this principal may access deployment-global connector configuration." } }, "required": ["role", "sub", "kind", "deploymentOwner"] } } } }, "401": { "description": "Admin authentication is required." } } } }, "/admin/settings": { "get": { "tags": ["Admin · Health & settings"], "summary": "Read runtime settings", "description": "Content mode, feature flags, and other runtime-mutable settings. Requires the `config:read` capability.", "operationId": "adminGetSettings", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "tags": ["Admin · Health & settings"], "summary": "Update runtime settings", "description": "Update runtime-mutable settings. Requires the `content:manage` capability.", "operationId": "adminPutSettings", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/update-status": { "get": { "tags": ["Admin · Health & settings"], "summary": "Self-updater status", "description": "Available image tag vs the running version, the locally evaluated release preflight, the computed update class (`soft` = image-only, self-applies on Compose installs when the policy is on; `hard` = operator infra action required, never applied unattended), the `autoSoftUpdates` policy, and the last unattended apply attempt. Requires the `config:read` capability.", "operationId": "adminUpdateStatus", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "preflight": { "type": "object", "required": [ "target", "status", "missingEnv", "removedEnvSet", "breaking" ], "properties": { "target": { "type": ["string", "null"], "pattern": "^v?\\d+\\.\\d+\\.\\d+$" }, "status": { "type": "string", "enum": ["ok", "blocked", "unknown"] }, "missingEnv": { "type": "array", "items": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "pattern": "^ANYRAY_[A-Z0-9_]{1,60}$" }, "summary": { "type": "string", "maxLength": 200 }, "composeDefault": { "type": "boolean" } } } }, "removedEnvSet": { "type": "array", "items": { "type": "string", "pattern": "^ANYRAY_[A-Z0-9_]{1,60}$" } }, "breaking": { "type": "array", "items": { "type": "string", "maxLength": 300 } } } }, "updateClass": { "type": "string", "enum": ["soft", "hard", "unknown"] }, "autoSoftUpdates": { "type": "boolean", "description": "Whether soft (image-only) updates apply unattended. Default true." }, "autoUpdate": { "type": ["object", "null"], "description": "Last unattended apply attempt (in-memory; resets on gateway restart).", "properties": { "target": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "result": { "type": "string", "enum": ["triggered", "unreachable", "rejected"] } } } } } } } } } } }, "/admin/auth": { "get": { "tags": ["Admin · Health & settings"], "summary": "Auth-mode probe", "description": "Pre-session probe: reports whether console SSO is required. Unauthenticated.", "operationId": "adminAuthProbe", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/auth/update": { "get": { "tags": ["Admin · Health & settings"], "summary": "Trigger self-update", "description": "Run a self-update check/apply. Requires the `update:run` capability.", "operationId": "adminAuthUpdate", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/optimizer/settings": { "get": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Read optimizer config", "description": "The optimizer pipeline configuration (strategies + params). Requires the `config:read` capability.", "operationId": "adminGetOptimizer", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Update optimizer config", "description": "Update the optimizer pipeline configuration. Requires the `optimizer:write` capability.", "operationId": "adminPutOptimizer", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/optimizer/purge": { "post": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Purge optimizer state", "description": "Purge optimizer caches / session state. Requires the `optimizer:purge` capability.", "operationId": "adminOptimizerPurge", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/pricing": { "get": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Official price table", "description": "The read-only official model price table. Requires the `config:read` capability.", "operationId": "adminPricing", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/model-aliases": { "get": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Read model aliases", "description": "Model-alias → target mappings. Requires the `config:read` capability.", "operationId": "adminGetAliases", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Update model aliases", "description": "Replace model-alias mappings. Requires the `modelaliases:write` capability.", "operationId": "adminPutAliases", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/routing-config": { "get": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Read routing config", "description": "Routing strategy (single / loadbalance / fallback / conditional) and targets. Requires the `config:read` capability.", "operationId": "adminGetRouting", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Update routing config", "description": "Update routing strategy and targets. See the Configure docs for the body shape. Requires the `routing:write` capability.", "operationId": "adminPutRouting", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/test-request": { "post": { "tags": ["Admin · Optimizer, pricing & routing"], "summary": "Playground test request", "description": "Send a test request through the gateway (console playground). Requires the `playground:run` capability.", "operationId": "adminTestRequest", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/provider-keys": { "get": { "tags": ["Admin · Providers"], "summary": "List provider slugs", "description": "Configured providers (slugs only — key values are never returned). Requires the `providerkeys:manage` capability.", "operationId": "adminGetProviderKeys", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "tags": ["Admin · Providers"], "summary": "Set provider keys", "description": "Set server-held provider API keys. Callers authenticate with a separate, minted Anyray client key and never receive the stored provider secret. Requires the `providerkeys:manage` capability.", "operationId": "adminPutProviderKeys", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/spend/connectors": { "get": { "tags": ["Admin · Providers"], "summary": "List seat-spend connectors (legacy path)", "description": "Compatibility facade for the previously released slash-separated connector path. It reads the same canonical encrypted connector store and returns a redacted legacy view for Cursor, Devin, and GitHub Copilot. Prefer `/admin/spend-connectors`. Preserves the released `providerkeys:manage` capability requirement and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.", "operationId": "adminGetLegacySpendConnectors", "deprecated": true, "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "Redacted legacy connector configuration. Credential values never appear.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacySpendConnectorsRead" } } } }, "401": { "description": "Admin authentication is required." }, "403": { "description": "The principal lacks `providerkeys:manage` or is not the deployment owner." }, "500": { "description": "Connector state could not be read. The response does not expose credentials or storage details." } } }, "put": { "tags": ["Admin · Providers"], "summary": "Set seat-spend connectors (legacy path)", "description": "Compatibility facade for legacy token-shaped Cursor, Devin, and GitHub Copilot writes. It transforms the old request shape and updates the same canonical encrypted connector store. Omitted sources stay unchanged; an empty string, empty or tokenless object, or `null` removes that source. An unscoped Copilot token is retained disabled. Prefer `/admin/spend-connectors`. Requires `providerkeys:manage` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.", "operationId": "adminPutLegacySpendConnectors", "deprecated": true, "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacySpendConnectorsPatch" } } } }, "responses": { "200": { "description": "The resulting redacted legacy connector configuration. Credential values are never echoed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacySpendConnectorsRead" } } } }, "400": { "description": "Invalid JSON, unsupported connector name, or invalid connector configuration." }, "401": { "description": "Admin authentication is required." }, "403": { "description": "The principal lacks `providerkeys:manage` or is not the deployment owner." }, "500": { "description": "The encrypted configuration could not be persisted. The response does not expose credentials or storage details." } } } }, "/admin/scim/settings": { "get": { "tags": [ "Admin · Access, SSO & enrollment" ], "summary": "Read inbound SCIM settings", "description": "Return whether inbound SCIM is configured plus the admin group and group-to-team map. The bearer and its hash are never returned. Requires `config:read` and deployment-owner access.", "operationId": "adminGetScimSettings", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "Redacted inbound SCIM settings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "configured", "adminGroup", "groupTeamMap", "updatedAt" ], "properties": { "configured": { "type": "boolean" }, "adminGroup": { "type": [ "string", "null" ] }, "groupTeamMap": { "type": "object", "additionalProperties": { "type": "string" } }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Admin authentication is required." }, "403": { "description": "The principal lacks `config:read` or is not the deployment owner." }, "503": { "description": "The shared SCIM settings store is unavailable." } } }, "put": { "tags": [ "Admin · Access, SSO & enrollment" ], "summary": "Configure inbound SCIM", "description": "Set or rotate the static SCIM bearer and update the admin group or group-to-team map. Omit `bearerToken` to preserve an existing credential. Requires `idp:manage` and deployment-owner access.", "operationId": "adminPutScimSettings", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bearerToken": { "type": "string", "minLength": 32, "maxLength": 1024, "writeOnly": true }, "adminGroup": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 256 }, "groupTeamMap": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The resulting redacted inbound SCIM settings." }, "400": { "description": "Invalid settings, or the first configuration omitted `bearerToken`." }, "401": { "description": "Admin authentication is required." }, "403": { "description": "The principal lacks `idp:manage` or is not the deployment owner." }, "503": { "description": "The shared SCIM settings store is unavailable." } } } }, "/admin/idp-config": { "get": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Read SSO/IdP config", "description": "The SSO / IdP configuration. Requires the `config:read` capability.", "operationId": "adminGetIdp", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Configure SSO/IdP", "description": "Set the SSO / IdP configuration. Requires the `idp:manage` capability.", "operationId": "adminPutIdp", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Remove SSO/IdP config", "description": "Remove the SSO / IdP configuration. Requires the `idp:manage` capability.", "operationId": "adminDeleteIdp", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK" } } } }, "/admin/connect/directives": { "post": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Queue a connect remediation directive", "description": "Queue a per-user remediation directive (RFC 0009 §4.3) for a developer identified by their pseudonymous `userHash` (from the per-user connect-health view). The developer's machine picks it up on its next `/connect/verify` and applies it — pull-only, never pushed. `kind` is one of `reapply_config` (re-apply the tool config), `remint`, or `revert`. Requires the `idp:manage` capability.", "operationId": "adminQueueConnectDirective", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["userHash", "kind"], "properties": { "userHash": { "type": "string", "description": "Pseudonymous developer id (HMAC-SHA256, base64url) from the per-user connect-health view." }, "kind": { "type": "string", "enum": ["reapply_config", "remint", "revert"] } } } } } }, "responses": { "200": { "description": "The queued directive.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/revoked-users": { "get": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "List revoked developers", "description": "The tenant's SSO developer-revocation set (offboarded emails and when each was revoked). Requires the `config:read` capability.", "operationId": "adminListRevokedUsers", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Revoke a developer", "description": "Offboard an SSO developer by email so the gateway refuses to re-mint their key (within one lease heartbeat). This is the offboarding path for orgs without WorkOS Directory Sync. Requires the `idp:manage` capability.", "operationId": "adminRevokeUser", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/admin/revoked-users/{email}": { "delete": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Reinstate a developer", "description": "Undo a revocation (IdP re-activation) for the given developer email. Requires the `idp:manage` capability.", "operationId": "adminReinstateUser", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/admin/workos-portal-link": { "post": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "WorkOS admin-portal link", "description": "Mint a WorkOS admin-portal link. Requires the `idp:manage` capability.", "operationId": "adminWorkosPortal", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/sso/start": { "get": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Begin SSO login", "description": "Start the console SSO login handshake. Pre-session (redirects).", "operationId": "adminSsoStart", "security": [], "responses": { "200": { "description": "OK" }, "302": { "description": "Redirect to the IdP." } } } }, "/admin/sso/callback": { "get": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "SSO callback", "description": "SSO redirect callback. Pre-session.", "operationId": "adminSsoCallback", "security": [], "responses": { "200": { "description": "OK" }, "302": { "description": "Redirect back to the console." } } } }, "/admin/sso/logout": { "post": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "End SSO session", "description": "End the console SSO session.", "operationId": "adminSsoLogout", "security": [], "responses": { "200": { "description": "OK" } } } }, "/admin/client-keys": { "get": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "List client keys", "description": "Minted client keys (enrolled users). Requires the `config:read` capability.", "operationId": "adminGetClientKeys", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Mint a client key", "description": "Mint a client key for an enrolled user. Requires the `clientkeys:manage` capability.", "operationId": "adminMintClientKey", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/client-keys/{id}": { "delete": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Revoke a client key", "description": "Revoke a minted client key. Requires the `clientkeys:manage` capability.", "operationId": "adminRevokeClientKey", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK" } } } }, "/admin/service-keys": { "get": { "tags": [ "Admin · Access, SSO & enrollment" ], "summary": "List service keys", "description": "List non-human service keys as metadata only. Raw tokens and hashes are never returned. Requires the `config:read` capability.", "operationId": "adminGetServiceKeys", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "Service-key roster", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceKeyListResponse" } } } } } }, "post": { "tags": [ "Admin · Access, SSO & enrollment" ], "summary": "Mint a service key", "description": "Mint a revocable `ark_svc_` key for an AI agent, CI job, or SDK script, optionally capped by successful request cost per UTC calendar month. The raw token is returned exactly once. Requires the `clientkeys:manage` capability.", "operationId": "adminMintServiceKey", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceKeyCreateRequest" } } } }, "responses": { "201": { "description": "Service key minted; save the raw key now because it cannot be recovered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceKeyMintResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/admin/service-keys/{id}": { "delete": { "tags": [ "Admin · Access, SSO & enrollment" ], "summary": "Revoke a service key", "description": "Revoke a service key by its opaque record id. Requires the `clientkeys:manage` capability.", "operationId": "adminRevokeServiceKey", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Service key revoked", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true } } } } } }, "404": { "description": "Unknown service-key id" } } } }, "/admin/enrollment-links": { "get": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "List enrollment links", "description": "Enrollment / setup links. Requires the `config:read` capability.", "operationId": "adminGetEnrollLinks", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Create enrollment link", "description": "Create an enrollment / setup link. Requires the `enrollment:manage` capability.", "operationId": "adminCreateEnrollLink", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/enrollment-links/{id}": { "delete": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Disable enrollment link", "description": "Disable an enrollment link. Requires the `enrollment:manage` capability.", "operationId": "adminDisableEnrollLink", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK" } } } }, "/admin/enrollment-links/{id}/hard": { "delete": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Hard-delete enrollment link", "description": "Permanently delete an enrollment link. Requires the `enrollment:manage` capability.", "operationId": "adminHardDeleteEnrollLink", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK" } } } }, "/admin/provisioning-tokens": { "get": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "List provisioning tokens", "description": "Deployment provisioning tokens. Requires the `config:read` capability.", "operationId": "adminGetProvTokens", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Mint provisioning token", "description": "Mint a deployment provisioning token. Requires the `provisioning:manage` capability.", "operationId": "adminMintProvToken", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/provisioning-tokens/{id}": { "delete": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Revoke provisioning token", "description": "Revoke a provisioning token. Requires the `provisioning:manage` capability.", "operationId": "adminRevokeProvToken", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK" } } } }, "/admin/provisioning-tokens/{id}/rotate": { "post": { "tags": ["Admin · Access, SSO & enrollment"], "summary": "Rotate provisioning token", "description": "Rotate a provisioning token. Requires the `provisioning:manage` capability.", "operationId": "adminRotateProvToken", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/gdpr/users/{user}/export": { "get": { "tags": ["Admin · Privacy, support & observability"], "summary": "Export a user's records", "description": "Export a user's content-free spend, connector-observation, and client-key records (GDPR). Deployment-owner requests include deployment-global connector observations; tenant-scoped SSO requests return an empty `connectorRecords` array. Requires the `gdpr:manage` capability.", "operationId": "adminGdprExport", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Attributed user id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "generatedAt", "spendRecords", "connectorRecords", "clientKeys" ], "properties": { "user": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "spendRecords": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "connectorRecords": { "type": "array", "description": "Content-free vendor connector observations. Empty for tenant-scoped SSO requests.", "items": { "type": "object", "additionalProperties": true } }, "clientKeys": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } }, "/admin/gdpr/users/{user}": { "delete": { "tags": ["Admin · Privacy, support & observability"], "summary": "Erase a user's records", "description": "Erase a user's spend, client-key, trace, and eligible connector-observation records (GDPR). Only deployment-owner requests erase deployment-global connector observations; tenant-scoped SSO requests report `erasedConnectorRecords: 0`. Requires the `gdpr:manage` capability.", "operationId": "adminGdprErase", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Attributed user id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "erasedSpendRecords", "erasedConnectorRecords", "erasedClientKeys", "erasedTraces" ], "properties": { "user": { "type": "string" }, "erasedSpendRecords": { "type": "integer", "minimum": 0 }, "erasedConnectorRecords": { "type": "integer", "minimum": 0, "description": "Always 0 for tenant-scoped SSO requests." }, "erasedClientKeys": { "type": "integer", "minimum": 0 }, "erasedTraces": { "type": "integer", "minimum": 0 } } } } } } } } }, "/admin/support/bundle": { "get": { "tags": ["Admin · Privacy, support & observability"], "summary": "Support bundle", "description": "Generate a content-free support bundle for remote debugging. Requires the `config:read` capability.", "operationId": "adminSupportBundle", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/support/bundle/share": { "post": { "tags": ["Admin · Privacy, support & observability"], "summary": "Share a support bundle", "description": "Generate, redact, and explicitly send a content-free support bundle to the Anyray Billing app. Requires the `content:manage` capability; the send is recorded in the deployment audit log.", "operationId": "adminShareSupportBundle", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "Bundle accepted; returns the support receipt id and metadata-only manifest summary.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Authenticated role lacks the `content:manage` capability." }, "409": { "description": "Deployment is not connected to the Anyray Billing app." }, "502": { "description": "The Billing app did not accept the bundle." } } } }, "/admin/observability/traces/{id}": { "get": { "tags": ["Admin · Privacy, support & observability"], "summary": "Read a trace", "description": "Fetch one trace. Content is redacted unless the caller has `observability:read-content`. Other `/admin/observability/*` read paths proxy to the observability API. Requires the `observability:read` capability.", "operationId": "adminGetTrace", "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/team-skills": { "get": { "tags": ["Admin · Privacy, support & observability"], "summary": "Read team skills", "description": "Team-skill / onboarding metadata. Requires the `config:read` capability.", "operationId": "adminGetTeamSkills", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "tags": ["Admin · Privacy, support & observability"], "summary": "Update team skills", "description": "Update team-skill / onboarding metadata. Requires the `teamskills:write` capability.", "operationId": "adminPutTeamSkills", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/wizard-status": { "get": { "tags": ["Admin · Privacy, support & observability"], "summary": "Onboarding wizard status", "description": "Onboarding wizard progress. Requires the `config:read` capability.", "operationId": "adminWizardStatus", "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/wizard-confirm": { "put": { "tags": ["Admin · Privacy, support & observability"], "summary": "Confirm wizard step", "description": "Confirm an onboarding wizard step. Requires the `wizard:write` capability.", "operationId": "adminWizardConfirm", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/connect/policy": { "get": { "operationId": "getConnectPolicy", "tags": ["Connect · Coding-tool integration"], "summary": "Get the team optimization policy", "description": "Returns the org-wide optimization policy the connect hook applies locally (which strategies are enabled and their surface). Resolved from the team-skills config; content-free.", "security": [ { "ConnectKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Versioned, content-free fleet policy document. Absent optional fields are treated as unset by older/newer clients alike (backward-compatible).", "properties": { "version": { "type": "integer", "description": "Policy document schema version (1). A document with no version is treated as a legacy skills-only document." }, "skills": { "type": "array", "description": "Enabled team skills (content-free descriptors).", "items": { "type": "object", "additionalProperties": true } }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last policy change." }, "routing": { "type": "object", "description": "Gateway routing origin the client reconciles toward. Omitted when unset.", "properties": { "origin": { "type": "string" } }, "required": ["origin"] }, "team": { "type": "string", "description": "Team attribution bound to the caller's key. Omitted when the key carries no team." }, "tools": { "type": "object", "description": "Server-owned enabled tool-set. Reconcile is enable-only over already-managed tools and never resurrects a reverted tool.", "properties": { "enabled": { "type": "array", "items": { "type": "string" } } } } }, "required": ["skills", "updatedAt"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/connect/savings": { "get": { "operationId": "getConnectSavings", "tags": ["Connect · Coding-tool integration"], "summary": "Get this developer's savings summary", "description": "Content-free savings rollup for the key's attributed user over the current billing period — token counts and USD savings only, no prompt/response content.", "security": [ { "ConnectKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "Attributed user id." }, "team": { "type": ["string", "null"], "description": "Attributed team id, if any." }, "grossSavingsUsd": { "type": "number", "description": "Pre-scaling savings (value delivered)." }, "savingsUsd": { "type": "number", "description": "Billed savings for the period." }, "totalTokens": { "type": "integer", "description": "Total attributed tokens." }, "savedTokens": { "type": "integer", "description": "Tokens saved by the optimizer." } }, "required": ["user"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/connect/health": { "post": { "operationId": "recordConnectHealth", "tags": ["Connect · Coding-tool integration"], "summary": "Report connect-health check results", "description": "Best-effort, content-free rollup of `anyray-connect doctor` results (gateway reachability, retrieval loop, per-tool MCP registration, enrollment, connect run). The gateway folds these into a rolling 24h window forwarded to the Billing app on the next meter round, so the vendor fleet view can see client-side problems. Metadata only — closed-charset tokens and counts, never content. Accepts an unattributed report and always returns 200.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 512, "items": { "type": "object", "properties": { "tool": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$", "description": "Client/tool id (e.g. opencode, claude-code)." }, "checkId": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$", "description": "Doctor check id (e.g. gateway_reachable)." }, "status": { "type": "string", "pattern": "^[a-z0-9_]{1,32}$", "description": "Check result token (e.g. ok, unreachable)." }, "errorClass": { "type": "string", "pattern": "^[A-Za-z0-9_$.-]{1,64}$", "description": "Classified failure reason — a class name, never a message." } }, "required": ["tool", "checkId", "status"] } } }, "required": ["events"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok"] }, "recorded": { "type": "integer", "minimum": 0, "description": "Number of valid events recorded." } }, "required": ["status", "recorded"] } } } } } } }, "/connect/hook-savings": { "post": { "operationId": "recordHookSavings", "tags": ["Connect · Coding-tool integration"], "summary": "Record source-side hook savings", "description": "Best-effort beacon from the connect PostToolUse hook reporting tokens it trimmed from a tool output before it entered the transcript. Metadata only (a token count) — no content. Always returns 200.", "security": [ { "ConnectKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "estTokensSaved": { "type": "integer", "minimum": 0, "description": "Estimated tokens trimmed at the source by the hook." } }, "required": ["estTokensSaved"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok"] }, "recorded": { "type": "boolean", "description": "Whether the beacon was attributed to a user." } }, "required": ["status"] } } } } } } }, "/connect/optimize-output": { "post": { "operationId": "optimizeHookOutput", "tags": ["Connect · Coding-tool integration"], "summary": "Optimize a tool output at the source", "description": "The connect PostToolUse hook posts a raw tool output; the gateway proxies it to the optimizer's output-trim pass and returns the (possibly trimmed) text plus a content-free retrieval handle for the stashed original. Trimming at the source keeps the transcript cache-safe by construction.", "security": [ { "ConnectKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string", "description": "Raw tool output to trim." }, "tool": { "type": "string", "description": "Originating tool name (routing hint)." }, "context": { "type": "object", "description": "Optional content-free hints (e.g. estimated size).", "additionalProperties": true } }, "required": ["output"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string", "description": "Trimmed output to write into the transcript." }, "optimized": { "type": "boolean", "description": "Whether any trim was applied." }, "handle": { "type": ["string", "null"], "description": "Content-free retrieval handle for the stashed original, or null when nothing was stashed. Retrieve with POST /connect/retrieve." }, "savedTokens": { "type": "integer", "minimum": 0, "description": "Tokens trimmed, if any." } }, "required": ["output"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/connect/mcp-heartbeat": { "post": { "operationId": "connectMcpHeartbeat", "tags": ["Connect · Coding-tool integration"], "summary": "MCP server session-start heartbeat", "description": "Called by the anyray-connect MCP server when a coding session initializes. A key-verified call records that explicit handle retrieval is available on this client. It does not override the persistent-client safety gate because MCP results are appended rather than restored in place. Empty body; the evidence decays after 30 days without a refresh.", "security": [ { "ConnectKey": [] } ], "responses": { "204": { "description": "Capability evidence latched (no body)." }, "401": { "description": "Missing or invalid client key." } } } }, "/connect/retrieve": { "post": { "operationId": "retrieveConnectHandle", "tags": ["Connect · Coding-tool integration"], "summary": "Retrieve a stashed original by handle", "description": "Fetches the full original content stashed by a prior optimize-output/CCR trim, keyed by its content-free handle. Proxies the optimizer's `/v1/retrieve`. Returns the content to the client that owns the handle only.", "security": [ { "ConnectKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Content-free handle returned by optimize-output." } }, "required": ["handle"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "The requested handle." }, "content": { "type": "string", "description": "The stashed original content." }, "found": { "type": "boolean", "description": "Whether the handle resolved." } }, "required": ["handle"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Handle not found or expired." } } } }, "/connect/recall": { "post": { "operationId": "recallConnectContext", "tags": ["Connect · Coding-tool integration"], "summary": "Semantic recall over stashed context", "description": "Ranks previously-stashed context against a query and returns the best content-free match handles (with a relevance score and a short preview). The client fetches full content via POST /connect/retrieve. Proxies the optimizer recall pass.", "security": [ { "ConnectKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Query to rank stashed context against." }, "limit": { "type": "integer", "minimum": 1, "description": "Max matches to return." } }, "required": ["query"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok", "unavailable"] }, "matches": { "type": "array", "description": "Ranked content-free matches (empty when unavailable).", "items": { "type": "object", "properties": { "handle": { "type": "string", "description": "Retrieval handle for POST /connect/retrieve." }, "score": { "type": "number", "description": "Relevance score." }, "preview": { "type": "string", "description": "Short preview snippet of the match." } }, "required": ["handle", "score", "preview"] } } }, "required": ["status"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/sso/cli/start": { "post": { "operationId": "startCliSsoLogin", "tags": [ "Connect · SSO enrollment" ], "summary": "Start a self-service CLI SSO login", "description": "Creates a durable ten-minute gateway session and a deployment-authenticated Billing app identity grant. Returns the browser URL, human confirmation code, and a separate poll capability. The endpoint is unauthenticated and rate-limited by source IP.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "SSO login started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "browser_url", "user_code", "poll_secret", "interval", "expires_in" ], "properties": { "id": { "type": "string" }, "browser_url": { "type": "string", "format": "uri" }, "user_code": { "type": "string", "pattern": "^[A-Z2-9]{4}-[A-Z2-9]{4}$" }, "poll_secret": { "type": "string", "description": "High-entropy poll capability returned once; never put it in a URL or log." }, "interval": { "type": "integer", "minimum": 1 }, "expires_in": { "type": "integer", "minimum": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "description": "Source-IP start rate limit exceeded." }, "503": { "description": "The identity authority or durable session store is unavailable." } } } }, "/sso/cli/poll/{id}": { "get": { "operationId": "pollCliSsoLogin", "tags": [ "Connect · SSO enrollment" ], "summary": "Poll SSO completion and mint the selected team key", "description": "Returns pending until WorkOS verifies the identity, then returns the governed team list. Send one eligible team in `x-anyray-team` to atomically mint and receive the personal key once.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-anyray-poll-secret", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Separate high-entropy poll capability from the start response." }, { "name": "x-anyray-team", "in": "header", "required": false, "schema": { "type": "string" }, "description": "One team from the verified team-selection response." } ], "responses": { "200": { "description": "Team selection is available, or the selected team key was minted and returned once." }, "202": { "description": "Browser SSO is still pending." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Another request is minting the key." }, "410": { "description": "The login expired or was already consumed." }, "503": { "description": "The identity authority, key store, or durable session store is unavailable." } } } }, "/connect/verify": { "post": { "operationId": "verifyConnectDevCert", "tags": ["Connect · Coding-tool integration"], "summary": "Verify a dev cert and mint a connect key", "description": "Unauthenticated (rate-limited) enrollment endpoint. The client presents a signed dev-cert proof (`cert` + `challenge` + `sig`); on success the gateway verifies the signature offline and mints an `ark_` connect key bound to the cert's user/team, persisted in the shared spend DB. This is how a developer obtains the ConnectKey the other `/connect/*` routes require.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Dev-cert proof. Content-free — identity material only.", "properties": { "cert": { "type": "object", "description": "The signed dev cert (user/team, issuer, expiry, public key).", "additionalProperties": true }, "challenge": { "type": "string", "description": "Server-issued challenge nonce the client signed." }, "sig": { "type": "string", "description": "Signature over the challenge, verifiable against the cert." } }, "required": ["cert", "challenge", "sig"] } } } }, "responses": { "200": { "description": "Verified — key minted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "The minted `ark_` connect key." }, "user": { "type": "string", "description": "Attributed user id from the cert." }, "team": { "type": ["string", "null"], "description": "Attributed team id, if the cert carried one." }, "expiresAt": { "type": ["string", "null"], "description": "Key expiry (ISO-8601), or null if non-expiring.", "format": "date-time" } }, "required": ["key", "user"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Proof invalid, expired, or signature verification failed." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/audio/speech": { "post": { "operationId": "createSpeech", "tags": ["Audio"], "summary": "Create speech (text-to-speech)", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "TTS model id." }, "input": { "type": "string", "description": "Text to synthesize." }, "voice": { "type": "string", "description": "Voice id." }, "response_format": { "type": "string", "description": "Audio container (e.g. `mp3`, `wav`, `opus`)." }, "speed": { "type": "number", "description": "Playback speed multiplier." } }, "required": ["model", "input", "voice"] } } } }, "responses": { "200": { "description": "Synthesized audio stream.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/audio/transcriptions": { "post": { "operationId": "createTranscription", "tags": ["Audio"], "summary": "Transcribe audio", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file to transcribe." }, "model": { "type": "string", "description": "Transcription model id." }, "language": { "type": "string", "description": "Optional ISO-639-1 language hint." }, "prompt": { "type": "string", "description": "Optional decoding prompt." }, "response_format": { "type": "string", "description": "Output format (`json`, `text`, `srt`, `verbose_json`, `vtt`)." } }, "required": ["file", "model"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/audio/translations": { "post": { "operationId": "createTranslation", "tags": ["Audio"], "summary": "Translate audio to English", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file to translate." }, "model": { "type": "string", "description": "Translation model id." }, "prompt": { "type": "string", "description": "Optional decoding prompt." }, "response_format": { "type": "string", "description": "Output format (`json`, `text`, `srt`, `verbose_json`, `vtt`)." } }, "required": ["file", "model"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/images/generations": { "post": { "operationId": "createImage", "tags": ["Images"], "summary": "Generate images", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Image model id." }, "prompt": { "type": "string", "description": "Text prompt describing the image." }, "n": { "type": "integer", "minimum": 1, "description": "Number of images to generate." }, "size": { "type": "string", "description": "Image dimensions (e.g. `1024x1024`)." }, "response_format": { "type": "string", "description": "`url` or `b64_json`." }, "quality": { "type": "string", "description": "Rendering quality." }, "style": { "type": "string", "description": "Rendering style." } }, "required": ["prompt"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/images/edits": { "post": { "operationId": "createImageEdit", "tags": ["Images"], "summary": "Edit an image", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "Source image to edit." }, "prompt": { "type": "string", "description": "Instruction describing the edit." }, "mask": { "type": "string", "format": "binary", "description": "Optional mask marking the region to edit." }, "model": { "type": "string", "description": "Image model id." }, "n": { "type": "integer", "minimum": 1, "description": "Number of edits to generate." }, "size": { "type": "string", "description": "Output dimensions." }, "response_format": { "type": "string", "description": "`url` or `b64_json`." } }, "required": ["image", "prompt"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/files": { "get": { "operationId": "listFiles", "tags": ["Files"], "summary": "List uploaded files", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "description": "A file object.", "additionalProperties": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } }, "post": { "operationId": "uploadFile", "tags": ["Files"], "summary": "Upload a file", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File contents to upload." }, "purpose": { "type": "string", "description": "Intended purpose (e.g. `batch`, `fine-tune`, `assistants`)." } }, "required": ["file", "purpose"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/files/{id}": { "get": { "operationId": "retrieveFile", "tags": ["Files"], "summary": "Retrieve a file's metadata", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "name": "id", "in": "path", "required": true, "description": "File id.", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "404": { "description": "File not found." } } }, "delete": { "operationId": "deleteFile", "tags": ["Files"], "summary": "Delete a file", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "name": "id", "in": "path", "required": true, "description": "File id.", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "404": { "description": "File not found." } } } }, "/v1/files/{id}/content": { "get": { "operationId": "retrieveFileContent", "tags": ["Files"], "summary": "Download a file's content", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "name": "id", "in": "path", "required": true, "description": "File id.", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "Raw file content.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "404": { "description": "File not found." } } } }, "/v1/batches": { "get": { "operationId": "listBatches", "tags": ["Batches"], "summary": "List batches", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "description": "A batch object.", "additionalProperties": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } }, "post": { "operationId": "createBatch", "tags": ["Batches"], "summary": "Create a batch", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input_file_id": { "type": "string", "description": "Id of the uploaded JSONL input file." }, "endpoint": { "type": "string", "description": "Target endpoint (e.g. `/v1/chat/completions`)." }, "completion_window": { "type": "string", "description": "Completion window (e.g. `24h`)." } }, "required": ["input_file_id", "endpoint", "completion_window"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" } } } }, "/v1/batches/{id}": { "get": { "operationId": "retrieveBatch", "tags": ["Batches"], "summary": "Retrieve a batch", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "name": "id", "in": "path", "required": true, "description": "Batch id.", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "404": { "description": "Batch not found." } } } }, "/v1/batches/{id}/cancel": { "post": { "operationId": "cancelBatch", "tags": ["Batches"], "summary": "Cancel a batch", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "name": "id", "in": "path", "required": true, "description": "Batch id.", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "404": { "description": "Batch not found." } } } }, "/v1/responses": { "post": { "operationId": "createResponse", "tags": ["Responses"], "summary": "Create a model response", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model id." }, "input": { "description": "Input text or structured input items (provider-defined shape)." } }, "required": ["model", "input"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "402": { "$ref": "#/components/responses/ServiceKeyBudgetExceeded" } } } }, "/v1/responses/{id}": { "get": { "operationId": "retrieveResponse", "tags": ["Responses"], "summary": "Retrieve a model response", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "name": "id", "in": "path", "required": true, "description": "Response id.", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible provider response, relayed verbatim.", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "404": { "description": "Response not found." } } }, "delete": { "operationId": "deleteResponse", "tags": ["Responses"], "summary": "Delete a model response", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "name": "id", "in": "path", "required": true, "description": "Response id.", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "404": { "description": "Response not found." } } } }, "/v1/responses/{id}/input_items": { "get": { "operationId": "listResponseInputItems", "tags": ["Responses"], "summary": "List a response's input items", "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.", "parameters": [ { "$ref": "#/components/parameters/ProviderHeader" }, { "$ref": "#/components/parameters/MetadataHeader" }, { "name": "id", "in": "path", "required": true, "description": "Response id.", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] }, { "AnyrayApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "description": "An input item.", "additionalProperties": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ClientKeyUnauthorized" }, "404": { "description": "Response not found." } } } }, "/admin/update/settings": { "put": { "tags": ["Admin · Health & settings"], "summary": "Update policy", "description": "Set whether soft (image-only, preflight-green) updates apply unattended (Compose installs; other platforms are always notify-only). Default on. Hard updates are never applied unattended regardless of this setting. Requires the `update:run` capability.", "operationId": "adminUpdateSettings", "security": [ { "AdminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["autoSoftUpdates"], "properties": { "autoSoftUpdates": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "autoSoftUpdates": { "type": "boolean" } } } } } }, "400": { "description": "Invalid autoSoftUpdates value" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Anyray client or service key, sent as `Authorization: Bearer `. Human `ark_` keys carry developer attribution; non-human `ark_svc_` keys carry service identity and may have a per-key monthly dollar budget. A valid minted key is ALWAYS required on `/v1/*` (no opt-out), and its bound identity is authoritative over the `x-anyray-metadata` header. The real upstream provider key is held server-side and never sent by the client." }, "AnyrayApiKey": { "type": "apiKey", "in": "header", "name": "x-anyray-api-key", "description": "The same Anyray client key, supplied via the `x-anyray-api-key` header instead of `Authorization: Bearer`. Takes precedence over the bearer header when both are present." }, "AdminToken": { "type": "http", "scheme": "bearer", "description": "Admin access: the break-glass `ANYRAY_ADMIN_TOKEN` as `Authorization: Bearer `, or a role-scoped console SSO session. Each /admin/* route also requires a capability (shown per operation); the admin token owner passes all capability checks." }, "ConnectKey": { "type": "apiKey", "in": "header", "name": "x-anyray-api-key", "description": "Connect (coding-tool) client key — an `ark_`-prefixed key minted by `POST /connect/verify` (or by an admin via the console / an enrollment link) and stored in the shared spend DB. Sent via the `x-anyray-api-key` header, or as `Authorization: Bearer ` when that header is absent. It carries the developer's user/team attribution; the `/connect/*` routes resolve identity from it. This is the same credential accepted on `/v1/*`, scoped here to the coding-tool integration surface." } }, "parameters": { "ProviderHeader": { "name": "x-anyray-provider", "in": "header", "required": false, "description": "Upstream provider id to route to (e.g. `openai`, `anthropic`, `vertex-ai`, `bedrock`, `azure-openai`). Optional when a default provider or routing config is configured server-side.", "schema": { "type": "string" } }, "MetadataHeader": { "name": "x-anyray-metadata", "in": "header", "required": false, "description": "Content-free attribution as a JSON object, e.g. `{\"user\":\"alice\",\"team\":\"platform\"}`. Used for spend attribution and per-user caps. Never carries prompt/response content.", "schema": { "type": "string" } }, "ConfigHeader": { "name": "x-anyray-config", "in": "header", "required": false, "description": "JSON routing config for this request (fallback list, load-balance weights, retry policy). Credentials are never carried here — they are resolved from the server-held key store.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Malformed request (failed Zod validation, bad JSON, or an unknown provider/model).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Authentication is missing or invalid. The response is content-free and never echoes a credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit or per-user monthly token cap exceeded. Honors `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServiceKeyBudgetExceeded": { "description": "The bound service key has reached its successful-request cost budget for the current UTC calendar month. The soft cap is fail-open when its durable counter is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceKeyBudgetExceeded" } } } }, "ClientKeyUnauthorized": { "description": "A personal gateway key is missing, unknown, expired, or revoked. The response is content-free and never echoes a credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientKeyUnauthorized" } } } } }, "schemas": { "ChatCompletionRequest": { "type": "object", "required": ["model", "messages"], "description": "OpenAI-compatible chat completion request. Unlisted OpenAI fields are passed through to the provider.", "properties": { "model": { "type": "string", "minLength": 1, "description": "Model id or alias (e.g. `gpt-4o`, `claude-sonnet-4-5`)." }, "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChatMessage" } }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 1 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Max output tokens (legacy field)." }, "max_completion_tokens": { "type": "integer", "minimum": 1, "description": "Max output tokens (preferred field)." }, "n": { "type": "integer", "minimum": 1, "default": 1 }, "stream": { "type": "boolean", "default": false, "description": "Stream the response as server-sent events." }, "stop": { "description": "Up to 4 stop sequences.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "presence_penalty": { "type": "number", "minimum": -2, "maximum": 2 }, "frequency_penalty": { "type": "number", "minimum": -2, "maximum": 2 }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tool/function definitions, OpenAI tool-calling format." }, "tool_choice": { "description": "Controls which tool is called.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "response_format": { "type": "object", "additionalProperties": true }, "seed": { "type": "integer" }, "user": { "type": "string", "description": "End-user identifier passed to the provider. Use `x-anyray-metadata` for Anyray attribution." } }, "additionalProperties": true }, "ChatMessage": { "type": "object", "required": ["role"], "properties": { "role": { "type": "string", "enum": ["system", "user", "assistant", "tool", "developer"] }, "content": { "description": "Message content — a string, or an array of typed content parts (text/image).", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "type": "null" } ] }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_call_id": { "type": "string" } }, "additionalProperties": true }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/ChatMessage" }, "finish_reason": { "type": "string" } } } }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": true }, "EmbeddingRequest": { "type": "object", "required": ["model", "input"], "properties": { "model": { "type": "string", "minLength": 1 }, "input": { "description": "Text(s) to embed.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] }, "dimensions": { "type": "integer", "minimum": 1, "description": "Truncate the output embedding to this many dimensions (if the model supports it)." }, "encoding_format": { "type": "string", "enum": ["float", "base64"] }, "user": { "type": "string" } }, "additionalProperties": true }, "EmbeddingResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "embedding" }, "index": { "type": "integer" }, "embedding": { "type": "array", "items": { "type": "number" } } } } }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": true }, "MessagesRequest": { "type": "object", "required": ["model", "messages", "max_tokens"], "description": "Anthropic-native Messages request. Unlisted Anthropic fields are passed through.", "properties": { "model": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": ["user", "assistant"] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] } }, "additionalProperties": true } }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Maximum output tokens (required by the Anthropic API)." }, "system": { "description": "System prompt — a string or an array of content blocks.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "top_k": { "type": "integer", "minimum": 0 }, "stream": { "type": "boolean", "default": false }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_choice": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "MessagesResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "message" }, "role": { "type": "string", "const": "assistant" }, "model": { "type": "string" }, "content": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "stop_reason": { "type": ["string", "null"] }, "stop_sequence": { "type": ["string", "null"] }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "Model": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "model" }, "created": { "type": "integer" }, "owned_by": { "type": "string" } }, "additionalProperties": true }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "additionalProperties": true }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": ["string", "null"] }, "param": { "type": ["string", "null"] } }, "additionalProperties": true } }, "additionalProperties": true }, "ClientKeyUnauthorized": { "type": "object", "additionalProperties": false, "required": ["status", "code", "message", "hint"], "properties": { "status": { "type": "string", "const": "failure" }, "code": { "type": "string", "enum": ["missing_key", "key_unknown", "key_expired", "key_revoked"] }, "message": { "type": "string", "const": "valid client key required" }, "hint": { "type": "string", "description": "Bounded, content-free remediation for the reason code." } } }, "ServiceKeyCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "team" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Service identity name; also stored as the key label." }, "team": { "type": "string", "minLength": 1 }, "monthlyBudgetUsd": { "type": "number", "minimum": 0, "description": "Optional successful-request cost cap for one UTC calendar month. Omit or set to 0 for unlimited." } } }, "ServiceKeyRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "user", "team", "tenant", "label", "createdAt", "keyType", "source", "type" ], "properties": { "id": { "type": "string" }, "user": { "type": "string" }, "team": { "type": "string" }, "tenant": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time" }, "keyType": { "type": "string", "const": "service" }, "monthlyBudgetUsd": { "type": "number", "minimum": 0 }, "source": { "type": "string", "const": "service" }, "type": { "type": "string", "const": "service" } } }, "ServiceKeyMintResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "record" ], "properties": { "key": { "type": "string", "pattern": "^ark_svc_", "description": "Raw token, returned exactly once and never stored." }, "record": { "$ref": "#/components/schemas/ServiceKeyRecord" } } }, "ServiceKeyListResponse": { "type": "object", "additionalProperties": false, "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceKeyRecord" } } } }, "ServiceKeyBudgetExceeded": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "const": "service_key_budget_exceeded" }, "message": { "type": "string" } } } } }, "UsageBucket": { "type": "object", "properties": { "requests": { "type": "integer" }, "totalTokens": { "type": "integer" }, "promptTokens": { "type": "integer" }, "completionTokens": { "type": "integer" }, "costUsd": { "type": "number", "description": "List price of what ran." }, "spendUsd": { "type": "number", "description": "Real out-of-pocket (subscription seats spend only their overage)." }, "savingsUsd": { "type": "number", "description": "Billed savings." }, "grossSavingsUsd": { "type": "number", "description": "Pre-scaling savings; use for cross-user comparisons." } } }, "UserCapGauge": { "type": "object", "nullable": true, "properties": { "monthlyTokens": { "type": "integer" }, "usedTokens": { "type": "integer", "description": "Current calendar month, whatever window is shown." }, "pctUsed": { "type": "number" } } }, "UsageUser": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UsageBucket" } ], "properties": { "user": { "type": "string" }, "team": { "type": "string", "nullable": true }, "subscriptionTokens": { "type": "integer", "description": "Tokens on subscription-seat rows (>0 marks a seat)." }, "seatExcluded": { "type": "boolean", "description": "Matches ANYRAY_SEAT_EXCLUDE (bot/service account)." }, "cap": { "$ref": "#/components/schemas/UserCapGauge" }, "byModel": { "type": "array", "items": { "type": "object" }, "description": "Per-model UsageBucket + model id, heaviest first." }, "byDay": { "type": "array", "items": { "type": "object" }, "description": "Per-UTC-day usage, ascending." } } }, "SpendUsage": { "type": "object", "properties": { "window": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "totalUsers": { "type": "integer" }, "truncated": { "type": "boolean" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UsageUser" } }, "byModel": { "type": "array", "items": { "type": "object" }, "description": "Org-wide per-model rollup incl. distinct-user reach." }, "capAlerts": { "type": "object", "properties": { "thresholds": { "type": "array", "items": { "type": "number" } }, "webhookConfigured": { "type": "boolean" } } } } }, "AuthEvents": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuthEvent" } } } }, "AuthEvent": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time" }, "reason": { "type": "string" }, "hint": { "type": "string" }, "userRef": { "type": "string" }, "keyPrefix": { "type": "string", "description": "Short prefix only; never the full credential." }, "tool": { "type": "string" }, "toolVersion": { "type": "string" }, "replicaId": { "type": "string" } } }, "SpendConnectorPollCounts": { "type": "object", "required": ["fetched", "inserted", "duplicate"], "properties": { "fetched": { "type": "integer", "minimum": 0 }, "inserted": { "type": "integer", "minimum": 0 }, "duplicate": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "SpendConnectorPollStatus": { "type": "object", "required": [ "state", "leaseUntil", "lastAttemptAt", "consecutiveFailures" ], "properties": { "state": { "type": "string", "enum": ["running", "succeeded", "failed"] }, "leaseUntil": { "type": "string", "format": "date-time", "description": "Earliest instant at which another fleet replica may claim this connector." }, "lastAttemptAt": { "type": "string", "format": "date-time" }, "lastSuccessAt": { "type": "string", "format": "date-time" }, "lastFailureAt": { "type": "string", "format": "date-time" }, "consecutiveFailures": { "type": "integer", "minimum": 0 }, "lastResult": { "$ref": "#/components/schemas/SpendConnectorPollCounts" } }, "additionalProperties": false }, "SpendConnectorReadState": { "type": "object", "required": ["configured", "enabled"], "properties": { "configured": { "type": "boolean", "const": true }, "enabled": { "type": "boolean", "description": "Whether automatic polling is enabled. Disabled legacy credentials remain encrypted until rotated or removed." }, "status": { "$ref": "#/components/schemas/SpendConnectorPollStatus" } }, "additionalProperties": false }, "GithubCopilotSpendConnectorReadState": { "type": "object", "required": ["configured", "enabled"], "properties": { "configured": { "type": "boolean", "const": true }, "enabled": { "type": "boolean", "description": "Whether automatic polling is enabled." }, "scope": { "type": "string", "enum": ["organization", "enterprise"] }, "slug": { "type": "string", "description": "Non-secret GitHub organization or enterprise slug." }, "status": { "$ref": "#/components/schemas/SpendConnectorPollStatus" } }, "additionalProperties": false }, "SpendConnectorsRead": { "type": "object", "description": "Redacted connector state. Unconfigured connectors are omitted; credentials never appear.", "properties": { "cursor": { "$ref": "#/components/schemas/SpendConnectorReadState" }, "devin": { "$ref": "#/components/schemas/SpendConnectorReadState" }, "githubCopilot": { "$ref": "#/components/schemas/GithubCopilotSpendConnectorReadState" } }, "additionalProperties": false }, "CursorSpendConnectorCredential": { "type": "object", "required": ["adminApiKey"], "properties": { "adminApiKey": { "type": "string", "minLength": 1, "maxLength": 16384, "writeOnly": true, "description": "Cursor Teams Admin API key. Non-empty after trimming; encrypted at rest and never returned." }, "enabled": { "type": "boolean", "default": true, "description": "Set false to retain the encrypted credential without polling." } }, "additionalProperties": false }, "DevinSpendConnectorCredential": { "type": "object", "required": ["serviceUserToken"], "properties": { "serviceUserToken": { "type": "string", "minLength": 1, "maxLength": 16384, "writeOnly": true, "description": "Devin service-user token with consumption-read permission. Non-empty after trimming; encrypted at rest and never returned." }, "enabled": { "type": "boolean", "default": true, "description": "Set false to retain the encrypted credential without polling." } }, "additionalProperties": false }, "GithubCopilotSpendConnectorCredential": { "type": "object", "required": ["token"], "anyOf": [ { "required": ["scope", "slug"] }, { "required": ["enabled"], "properties": { "enabled": { "const": false } } } ], "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 16384, "writeOnly": true, "description": "GitHub token with Copilot usage-metrics read permission. Non-empty after trimming; encrypted at rest and never returned." }, "enabled": { "type": "boolean", "default": true, "description": "Set false to retain the encrypted credential without polling. Scope and slug are required whenever enabled is true." }, "scope": { "type": "string", "enum": ["organization", "enterprise"] }, "slug": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9_.-]+$", "description": "GitHub organization or enterprise slug for the selected scope." } }, "additionalProperties": false }, "SpendConnectorRemoval": { "type": "object", "maxProperties": 0, "additionalProperties": false, "description": "An empty object removes this connector; JSON `null` has the same effect." }, "SpendConnectorsPatch": { "type": "object", "description": "Partial connector update. Omitted properties stay unchanged; credential fields are write-only.", "properties": { "cursor": { "oneOf": [ { "$ref": "#/components/schemas/CursorSpendConnectorCredential" }, { "$ref": "#/components/schemas/SpendConnectorRemoval" }, { "type": "null" } ] }, "devin": { "oneOf": [ { "$ref": "#/components/schemas/DevinSpendConnectorCredential" }, { "$ref": "#/components/schemas/SpendConnectorRemoval" }, { "type": "null" } ] }, "githubCopilot": { "oneOf": [ { "$ref": "#/components/schemas/GithubCopilotSpendConnectorCredential" }, { "$ref": "#/components/schemas/SpendConnectorRemoval" }, { "type": "null" } ] } }, "additionalProperties": false }, "LegacySpendConnectorToken": { "type": "string", "minLength": 0, "maxLength": 16384, "writeOnly": true, "description": "Legacy vendor credential. An empty value removes the source; other values must be non-empty after trimming, are encrypted at rest, and are never returned." }, "LegacyCursorSpendConnectorPatch": { "anyOf": [ { "$ref": "#/components/schemas/LegacySpendConnectorToken" }, { "type": "object", "description": "Legacy token object. A missing or empty token removes Cursor.", "not": { "required": ["adminApiKey"] }, "properties": { "token": { "$ref": "#/components/schemas/LegacySpendConnectorToken" }, "enabled": { "type": "boolean", "default": true } }, "additionalProperties": true }, { "$ref": "#/components/schemas/CursorSpendConnectorCredential" }, { "type": "null" } ] }, "LegacyDevinSpendConnectorPatch": { "anyOf": [ { "$ref": "#/components/schemas/LegacySpendConnectorToken" }, { "type": "object", "description": "Legacy token object. A missing or empty token removes Devin.", "not": { "required": ["serviceUserToken"] }, "properties": { "token": { "$ref": "#/components/schemas/LegacySpendConnectorToken" }, "enabled": { "type": "boolean", "default": true } }, "additionalProperties": true }, { "$ref": "#/components/schemas/DevinSpendConnectorCredential" }, { "type": "null" } ] }, "LegacyCopilotSpendConnectorPatch": { "anyOf": [ { "$ref": "#/components/schemas/LegacySpendConnectorToken" }, { "type": "object", "description": "Legacy token object. A missing or empty token removes Copilot; a token without an org or enterprise is retained disabled.", "not": { "required": ["scope", "slug"] }, "properties": { "token": { "$ref": "#/components/schemas/LegacySpendConnectorToken" }, "enabled": { "type": "boolean", "default": true }, "org": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9_.-]+$" }, "enterprise": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9_.-]+$" } }, "additionalProperties": true }, { "$ref": "#/components/schemas/GithubCopilotSpendConnectorCredential" }, { "type": "null" } ] }, "LegacySpendConnectorsPatch": { "type": "object", "properties": { "cursor": { "$ref": "#/components/schemas/LegacyCursorSpendConnectorPatch" }, "devin": { "$ref": "#/components/schemas/LegacyDevinSpendConnectorPatch" }, "copilot": { "$ref": "#/components/schemas/LegacyCopilotSpendConnectorPatch" }, "githubCopilot": { "$ref": "#/components/schemas/LegacyCopilotSpendConnectorPatch" } }, "additionalProperties": false }, "LegacySpendConnectorReadState": { "type": "object", "required": ["configured", "enabled"], "properties": { "configured": { "type": "boolean", "const": true }, "enabled": { "type": "boolean" }, "org": { "type": "string" }, "enterprise": { "type": "string" } }, "additionalProperties": false }, "LegacySpendConnectorsRead": { "type": "object", "required": ["connectors", "supportedVendors"], "properties": { "connectors": { "type": "object", "properties": { "cursor": { "$ref": "#/components/schemas/LegacySpendConnectorReadState" }, "devin": { "$ref": "#/components/schemas/LegacySpendConnectorReadState" }, "copilot": { "$ref": "#/components/schemas/LegacySpendConnectorReadState" } }, "additionalProperties": false }, "supportedVendors": { "type": "array", "minItems": 3, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": ["cursor", "devin", "copilot"] } } }, "additionalProperties": false }, "SpendConnectorName": { "type": "string", "enum": ["cursor", "devin", "githubCopilot"] }, "SpendConnectorSyncSuccess": { "type": "object", "required": ["connector", "fetched", "inserted", "duplicate"], "properties": { "connector": { "$ref": "#/components/schemas/SpendConnectorName" }, "fetched": { "type": "integer", "minimum": 0 }, "inserted": { "type": "integer", "minimum": 0 }, "duplicate": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "SpendConnectorSyncSkipped": { "type": "object", "required": ["connector", "skipped"], "properties": { "connector": { "$ref": "#/components/schemas/SpendConnectorName" }, "skipped": { "type": "boolean", "const": true, "description": "Another replica owns the connector's durable poll lease." } }, "additionalProperties": false }, "SpendConnectorSyncFailed": { "type": "object", "required": ["connector", "failed"], "properties": { "connector": { "$ref": "#/components/schemas/SpendConnectorName" }, "failed": { "type": "boolean", "const": true, "description": "The vendor sync failed. No vendor error body, URL, or credential is exposed." } }, "additionalProperties": false }, "SpendConnectorSyncResult": { "oneOf": [ { "$ref": "#/components/schemas/SpendConnectorSyncSuccess" }, { "$ref": "#/components/schemas/SpendConnectorSyncSkipped" }, { "$ref": "#/components/schemas/SpendConnectorSyncFailed" } ] }, "SpendConnectorSyncResponse": { "type": "object", "required": ["connectors"], "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/SpendConnectorSyncResult" } } }, "additionalProperties": false }, "SpendConnectorCursorUsage": { "type": "object", "required": [ "events", "users", "tokens", "listPriceUsd", "paidExtraUsd", "requestUnits" ], "properties": { "events": { "type": "integer", "minimum": 0 }, "users": { "type": "integer", "minimum": 0 }, "tokens": { "type": "number", "minimum": 0 }, "listPriceUsd": { "type": "number", "minimum": 0, "description": "Published model value in USD; distinct from paid-extra spend." }, "paidExtraUsd": { "type": "number", "minimum": 0, "description": "Vendor-confirmed usage-based amount charged beyond included subscription usage." }, "requestUnits": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "SpendConnectorDevinUsage": { "type": "object", "required": ["days", "acus", "byProduct"], "properties": { "days": { "type": "integer", "minimum": 0, "description": "Distinct closed Devin billing days represented." }, "acus": { "type": "number", "minimum": 0, "description": "Vendor-native Agent Compute Units; never converted to tokens or USD." }, "byProduct": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 } } }, "additionalProperties": false }, "SpendConnectorGithubCopilotUsage": { "type": "object", "required": [ "userDays", "users", "cliTokens", "aiCreditsUsed", "aiCreditsListValueUsd", "interactions", "generations", "acceptances" ], "properties": { "userDays": { "type": "integer", "minimum": 0 }, "users": { "type": "integer", "minimum": 0 }, "cliTokens": { "type": "number", "minimum": 0, "description": "Provider-reported Copilot CLI prompt plus output tokens." }, "aiCreditsUsed": { "type": "number", "minimum": 0, "description": "Vendor-native AI credits." }, "aiCreditsListValueUsd": { "type": "number", "minimum": 0, "description": "Public GitHub list value at $0.01 per reported AI credit; visibility only, not an invoice total." }, "interactions": { "type": "number", "minimum": 0 }, "generations": { "type": "number", "minimum": 0 }, "acceptances": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "SpendConnectorUsage": { "type": "object", "required": ["from", "to", "cursor", "devin", "githubCopilot"], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "cursor": { "$ref": "#/components/schemas/SpendConnectorCursorUsage" }, "devin": { "$ref": "#/components/schemas/SpendConnectorDevinUsage" }, "githubCopilot": { "$ref": "#/components/schemas/SpendConnectorGithubCopilotUsage" } }, "additionalProperties": false }, "UserCap": { "type": "object", "required": ["monthlyTokens"], "properties": { "monthlyTokens": { "type": "integer", "minimum": 1, "description": "Positive whole token ceiling for the calendar month." } } }, "UserCapsGet": { "type": "object", "properties": { "config": { "type": "object", "properties": { "caps": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserCap" } }, "alerts": { "type": "object", "properties": { "thresholds": { "type": "array", "items": { "type": "number" } }, "webhookConfigured": { "type": "boolean", "description": "The webhook URL itself is write-only and never returned." } } } } }, "usage": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Current-month tokens per user." }, "period": { "type": "string", "example": "2026-07" } } }, "UserCapsPut": { "type": "object", "required": ["caps"], "properties": { "caps": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserCap" } }, "alerts": { "type": "object", "properties": { "webhookUrl": { "type": "string", "nullable": true, "description": "Slack-compatible incoming webhook. Absent = keep, null = clear, string = set. Write-only." }, "thresholds": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Cap fractions (0