{ "x-anyroute-telegram-menu": { "documentation": "/docs/#telegram-menu", "description": "J179: /menu in linked private Telegram chats delegates Balance, Spend, Agents and Stop all to their existing command handlers and permissions. Waiting approvals reuses Telegram approval delivery, lists up to ten oldest pending unexpired requests the current linked principal may decide, respects the approvals Telegram switch and refreshes existing message bindings. Approve and Deny retain their current single-use decision rules. Callback actions are bound to the current link generation. Inbox opens /dashboard/#inbox and Settings opens /dashboard/#notifications with normal site sign-in. No new HTTP endpoint, request field, migration or flag; requires existing TELEGRAM_LINKING_ENABLED and AGENT_POLICY_ENABLED (both default false), plus the existing bot token and worker. No new background job or notice type." }, "x-anyroute-telegram-photos": { "card": "D142", "flag": "TELEGRAM_PHOTOS_ENABLED", "default": false, "documentation": "/docs/#telegram-photos", "description": "Private human Telegram photos only. Connected API key auth on existing POST /api/v1/chat/completions; existing multimodal messages, billing, spending limits, receipts and attested-lane guard. Largest available size up to 8 MB; baseline JPEG coefficients re-encoded without EXIF or application metadata in memory. No photo persistence. Caption or fixed question. Non-vision models receive up to three catalog vision suggestions and /model instructions. No new HTTP endpoint or request field. Off preserves the text-only reply." }, "x-e149-read-only-keys": { "creation": "POST /api/v1/keys with management Bearer authentication and scope: read; omit management and team", "scope_values": [ "account", "inference", "read" ], "fixed_at_creation": true, "visibility": "owner account reads on the explicit GET allow-list in /docs/#read-only-keys, subject to existing feature flags and ownership guards", "refusal": "403 read_only_key for all other methods and paths, including paid GET tools, wallet actions and secret endpoints", "ip_allowlist": "Existing owner PATCH allowed_ips and ingress checks apply", "flag": null }, "openapi": "3.1.0", "x-agreements-jury": { "internal_flag": "AGREEMENT_JURY_INTERNAL_ENABLED", "default": false, "description": "AnyRoute runs a full distinct-model jury on fresh attested candidates. Enable internal transport to use stored provider credentials when AGREEMENT_JURY_API_KEY is unset; a set key retains billed chat routing. Dry-run stores would-be rulings on an ordinary worker without chain signer keys or a key log. Posting requires signer keys, TLOG_ENABLED, isolated agreement-jury worker and AGENT_AGREEMENTS_RULINGS_ENABLED. Auto selects three sorted currently selectable models; insufficient models remain awaiting jury. Votes retain router-signed operational receipts and provider attestation or checked gateway receipt references. Operator cost is a list-price estimate in the jury statement; no customer billing rows. Router reads evidence in memory. Complete hung tallies permit external panel fallback; failed or abstaining votes remain unresolved." }, "x-agreements-contracts": { "status": "not deployed at anyroute.tech yet", "flag": "AGENT_AGREEMENTS_ENABLED", "default": false, "documentation": "/docs/#agreements", "privacy": "Public milestone state, votes and signer-order tallies; signatures do not prove model execution or hardware attestation. The optional service stores readable party evidence and model reasons." }, "info": { "title": "Anyroute API", "version": "1.0.0", "description": "Scope: a documented subset of the public HTTP API that the Anyroute router implements. It covers the model catalog, chat completions, embeddings, key creation and listing, generations, status, health and receipts, plus the blind-token issuer keys and purchase (present only when the router enables blind tokens) the Oblivious HTTP gateway keys, gateway and relay list (present only when the router enables Oblivious HTTP) the transparency log of keys and configurations with its tiles, checkpoints and witness cosignatures (present only when the router enables it) the Lane: model variants, day-zero candidates and creator royalty claims, Private RAG (answers from documents sent with the question, nothing kept), and the Batch API (many chat or embeddings requests run in the background at a discount, with the lines and answers kept sealed outside the database until the results expire). It also covers teams as anonymous organisations: roles, passkey and wallet members, org budgets and the hash-chained audit log with its export, and characters: Tavern cards called as @character/, with a memory ledger encrypted on the client. Other implemented routes (for example legacy completions, the /v1 aliases, key updates, credits, Stock Token payments, BYOK, wallet sign-in, rankings, provider onboarding and the paymaster) are not described here, and a route's absence from this document does not mean it is absent from the router. Endpoint availability, payment modes and model capabilities are deployment-specific. Errors share the OpenRouter-shaped ApiError body; the 4xx responses each operation can return are declared with the reusable responses in components.responses.", "contact": { "name": "AnyRoute support", "email": "Anyroute1@atomicmail.io" }, "license": { "name": "PolyForm Noncommercial License 1.0.0", "identifier": "PolyForm-Noncommercial-1.0.0" }, "x-api-coverage": "subset" }, "externalDocs": { "description": "Developer documentation and endpoint overview", "url": "/docs/" }, "servers": [ { "url": "/", "description": "Current router origin" } ], "security": [ {} ], "tags": [ { "name": "Projects", "description": "D139: monthly project budgets" }, { "name": "Facilitator", "description": "Hosted x402 facilitator for USDG on Robinhood Chain (eip155:4663), x402 v1 and v2, scheme exact. Settlement is transferWithAuthorization from the payer straight to payTo; the relay key only pays gas. FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator." }, { "name": "Webhooks", "description": "Optional signed account event notices; WEBHOOK_SIGNING_ENABLED defaults to false." }, { "name": "Data tools", "description": "Read-only market data for agents, charged per call: Stock Token prices from Chainlink feeds on Robinhood Chain, corporate-action (multiplier) status and the inference price index. DATA_TOOLS_ENABLED defaults to false; every route answers 404 data_tools_disabled while it is off. A refusal (unknown symbol, stale feed, paused token, index without fills) is answered before any payment and is never charged." }, { "name": "Agent rulebook", "description": "Deterministic router enforcement for requests through AnyRoute only; AGENT_POLICY_ENABLED defaults to false. No on-chain enforcement." }, { "name": "Playbooks", "description": "One named rulebook that many keys of an account or team follow; a change applies to every following key from its next request. Same switch, roles and validation as the agent rulebook: AGENT_POLICY_ENABLED defaults to false." }, { "name": "Network host policy", "description": "Versioned signed build pins for future network host admission; existing provider admission is unchanged." }, { "name": "Models", "description": "Public model catalog and capabilities." }, { "name": "Chat", "description": "Chat completion requests and streaming responses." }, { "name": "Embeddings", "description": "Authenticated prepaid embedding requests." }, { "name": "Keys", "description": "API key creation and account key metadata." }, { "name": "Generations", "description": "Authenticated generation summaries and details." }, { "name": "Status", "description": "Public process and router configuration status." }, { "name": "Receipts", "description": "Public signed receipt retrieval and verification." }, { "name": "Saved Routes", "description": "Named routing policies callable as model @route/." }, { "name": "Presets", "description": "Versioned configs callable as model @preset/ or @preset/@: a saved route plus a system prompt, tools and a response_format, with diff and rollback." }, { "name": "Agent Sessions", "description": "Short-lived, budget-capped session keys for agent runs." }, { "name": "Spend Watch", "description": "Spend reports, key budgets and alert rules." }, { "name": "MCP", "description": "Remote Model Context Protocol server: every live model as a tool." }, { "name": "Anthropic Messages", "description": "Anthropic Messages API (POST /v1/messages, count_tokens) for the Anthropic SDKs and Claude Code, on the same keys, lanes and signed receipts as chat completions." }, { "name": "Holders", "description": "$ANYR holder balance, live tier, perks and free inference credits." }, { "name": "Blind tokens", "description": "Unlinkable paid access with Privacy Pass tokens (RFC 9578 type 0x0002, blind RSA per RFC 9474). Present only when the router enables blind tokens." }, { "name": "Oblivious HTTP", "description": "Oblivious HTTP gateway (RFC 9458) and the relays that reach it, behind the unlinkable lane. Present only when the router enables Oblivious HTTP." }, { "name": "Disclosure", "description": "What each provider has documented about how it handles a prompt (retention, jurisdiction, legal hold, training use), and the request options that route on it." }, { "name": "Lane", "description": "Model variants (mainstream, native_low_refusal, abliterated) with license and weights provenance, the rule that keeps restricted variants on attested providers, and the operator's day-zero candidate pipeline." }, { "name": "Creator royalties", "description": "Claim a model's creator royalty by publishing a challenge in the Hugging Face repository the weights come from." }, { "name": "Responses", "description": "OpenAI Responses API compatible endpoint for the OpenAI Agents SDK, the Codex CLI and other Responses clients. Stateless: nothing is stored." }, { "name": "Private RAG", "description": "Answers from documents sent with the question, ranked in memory and kept nowhere, through the router's own embeddings and chat routes." }, { "name": "Transparency log", "description": "An append-only log (C2SP tlog-tiles, RFC 6962 hashing) of the keys and configurations clients encrypt to or verify against: receipt keys, Oblivious HTTP key configurations, blind-token issuer keys, measurement bundles and sidecar key bindings. Checkpoints are signed notes (C2SP tlog-checkpoint) that witnesses cosign (C2SP tlog-cosignature, cosignature/v1). With TLOG_REKOR_ENABLED, each new checkpoint is also recorded in Sigstore's Rekor log (a hashedrekord entry signed with an ECDSA P-256 anchoring key), an alternative to witnesses. Present only when the router enables it (TLOG_ENABLED)." }, { "name": "Ollama", "description": "The Ollama API under /ollama for Ollama clients (Open WebUI, Continue, the ollama libraries, LangChain's ChatOllama): set the client's host to /ollama. Chat, generate and embed calls run on the same keys, lanes and signed receipts as chat completions; the key is sent as Authorization: Bearer." }, { "name": "Batches", "description": "The Batch API: many chat completions or embeddings requests sent in one call and run in the background on the router's worker, at 50% of the normal price, with results kept for 24 hours after the batch finishes." }, { "name": "Rerank", "description": "Rerank documents against a query (Cohere and Jina shape), billed per token or per search unit, with a signed receipt." }, { "name": "Teams", "description": "Anonymous organisations: an owner that is an account, a wallet or a Safe (EIP-1271), members who join by passkey or wallet, roles (owner, admin, dev, viewer, agent), an org budget, and a hash-chained audit log you can export and verify offline." }, { "name": "Status page", "description": "The public status page: availability, latency and error budgets per privacy lane and API surface, and incidents with Atom and RSS feeds. The public lane is summed from request outcomes; the attested and unlinkable lanes come only from the differentially private hourly releases at /api/v1/stats (source: dp-noised)." }, { "name": "Characters", "description": "Tavern character cards (V2 and V3, as JSON or PNG) called as model @character/: public, unlisted or private (encrypted on the client), with a chat endpoint that defaults to the attested lane, group turn order and creator attribution (counts and cost only)." }, { "name": "Memory", "description": "A memory ledger for characters, encrypted on the client: the router stores ciphertext under a scope it cannot link to a character, and embeddings only when the caller opts in." }, { "name": "Skills", "description": "Secured Skills Hub for agent skills (a folder with SKILL.md and its scripts and resources): import from a git repository or an archive, a static scan for data exfiltration, prompt injection, obfuscation, dangerous shell commands, untrusted package indexes and binaries, a sha256 content hash of a canonical tar, gated downloads and paid installs (90% to the author, 10% network fee) with a signed receipt. Scanned, not guaranteed." }, { "name": "Paid tools", "description": "Pay any x402 tool priced in USDG on Robinhood Chain from an Anyroute balance: rulebook price limits, holds, signed tool.call receipts, a listing catalog with daily known-answer canaries, and MCP tools anyroute_tools_search and anyroute_tools_call. Off unless TOOLS_MARKET_ENABLED." }, { "name": "Agent identity", "description": "ERC-8004 identity for opted-in agent profiles, paid-receipt feedback, liveness probes and portable track records. Off by default." } ], "paths": { "/api/v1/account/models/{id}/summary": { "get": { "operationId": "getAccountModelSummary", "summary": "Your view of a model", "description": "J178: composes existing readers using Activity visibility. Encode the complete model id as one path segment. No storage or new flag. Usage covers 30 rolling days; reliability covers 7. Read-only keys are refused. Price notices require non-session management access, PRICE_NOTICES_ENABLED and enabled inbox preferences; only the latest 101 retained notices are searched. Savings retain existing estimate limits.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "No-store summary: model and scope; usage with days/from/to and decimal-string calls/charged_usd/refunded_usd/cost_usd; reliability with days/from/to and decimal-string calls/succeeded and nullable numeric success_rate; nullable savings in the existing account savings model shape; nullable price_notice with at/title; boolean price_notices_visible." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/account/business-details": { "get": { "operationId": "getBusinessDetails", "tags": [ "Statements" ], "summary": "Read business details for statements", "description": "H168: follows STATEMENTS_ENABLED (default false). Auth and read visibility follow statements. The read-only allow-list is unchanged, so read keys must use the existing statement route with business_details=true instead of this settings route. Details are current, user-entered and unsigned.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "No-store. Current user-entered details or null; editable only for account management keys.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "editable" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/BusinessDetails" }, { "type": "null" } ] }, "editable": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "putBusinessDetails", "tags": [ "Statements" ], "summary": "Replace or delete business details", "description": "H168: account management keys only; session and team-only owner/admin keys cannot edit. All strings optional; omitted fields clear. Empty object or all-empty fields deletes business-details: from kv. No email field; reference rejects email addresses. Stored until replaced or deleted. Never changes the signed statement payload.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetails" } } } }, "responses": { "200": { "description": "No-store. Current user-entered details or null; editable only for account management keys.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "editable" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/BusinessDetails" }, { "type": "null" } ] }, "editable": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/account/savings": { "get": { "operationId": "accountSavings", "summary": "Find ways to save", "description": "G160: estimate the same charged input/output tokens at current catalogue token and request rates over 1 to 30 rolling days. Same Bearer key and account/key/session visibility as Activity; read-only keys are refused by the unchanged scope allow-list. Preserves all currently declared source modalities, parameters, full context and recorded lane/disclosure on one eligible endpoint. Uses closest cheaper token-weighted price; must be cheaper than both the current source rates and actual charges. Unknown metadata or unsafe billing omit the model. No equal quality claim. Excludes refunds, cache discounts, royalties, account fees and extra charges; historical ability changes cannot be reconstructed. No flag, worker, new storage or migration. See /docs/#savings-finder.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } } ], "responses": { "200": { "description": "Estimated comparisons at current catalogue prices; models empty when no safe cheaper match. Cache-Control: no-store.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "scope", "days", "from", "to", "priced_at", "estimate", "models" ], "properties": { "scope": { "type": "string", "enum": [ "account", "key" ] }, "days": { "type": "integer", "minimum": 1, "maximum": 30 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "priced_at": { "type": "string", "format": "date-time", "description": "Current catalogue snapshot time." }, "estimate": { "type": "string" }, "models": { "type": "array", "items": { "type": "object", "required": [ "model", "name", "calls", "tokens_in", "tokens_out", "charged_usd", "alternative" ], "properties": { "model": { "type": "string" }, "name": { "type": "string" }, "calls": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "tokens_in": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "tokens_out": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "charged_usd": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "alternative": { "type": "object", "required": [ "model", "name", "estimated_cost_usd", "estimated_saving_usd" ], "properties": { "model": { "type": "string" }, "name": { "type": "string" }, "estimated_cost_usd": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "estimated_saving_usd": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/account/browser-sessions": { "get": { "summary": "List signed-in browsers", "description": "E147: active account management Bearer key only; inference and agent session keys refused. Lists this account's active, unexpired wallet-issued root management keys. Older sign-ins have no browser details. last_used is the last charged call, not browsing. Sign out through existing DELETE /api/v1/keys/{hash}, or PATCH disabled=true for the current key. All others in Settings disables each other listed browser key after one confirmation and reports partial failures. No new flag or migration. Response Cache-Control is no-store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 100, "maximum": 1000 } } ], "responses": { "200": { "description": "Own active browser keys", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "properties": { "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "required": [ "hash", "browser_label", "created_at", "last_used", "current" ], "properties": { "hash": { "type": "string" }, "browser_label": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_used": { "type": [ "string", "null" ], "format": "date-time" }, "current": { "type": "boolean" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/harness/": { "get": { "x-card": "D137", "summary": "Open a shared Chat draft", "description": "Static Chat page; optional plain-text share fields prefill an unsent draft. Title cap 512, text cap 16000, URL cap 2048, combined cap 16384 characters. GET queries may reach hosting access logs. Sending separately requires normal Chat authentication and user action.", "security": [], "parameters": [ { "name": "share_title", "in": "query", "schema": { "type": "string", "maxLength": 512 } }, { "name": "share_text", "in": "query", "schema": { "type": "string", "maxLength": 16000 } }, { "name": "share_url", "in": "query", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "share_id", "in": "query", "description": "Opaque single-use worker-memory handoff id, usable for five minutes.", "schema": { "type": "string" } }, { "name": "share_error", "in": "query", "schema": { "type": "string", "enum": [ "invalid", "size", "images", "empty" ] } } ], "responses": { "200": { "description": "Chat with an unsent draft" } } }, "post": { "summary": "Receive a phone share in the installed app", "description": "Intercepted by the installed service worker, not a router endpoint. Original images remain in worker memory until single-use handoff, eviction or worker termination; expired shares are removed on the next share or handoff. Up to two pending shares. No body is forwarded to the server. Page uses the existing JPEG re-encoding path before attachment; never auto-sends. Without the worker this POST is unsupported.", "security": [], "parameters": [ { "name": "share_target", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "share_title": { "type": "string", "maxLength": 512 }, "share_text": { "type": "string", "maxLength": 16000 }, "share_url": { "type": "string", "maxLength": 2048 }, "share_files": { "type": "array", "maxItems": 6, "description": "PNG, JPEG, WebP or GIF only, each nonempty and at most 8 MB; entire multipart body at most 48 MB plus 64 KB.", "items": { "type": "string", "format": "binary" } } } } } } }, "responses": { "303": { "description": "Redirect to Chat with a handoff id or a fixed share error; no inference request" } } } }, "/api/v1/agents/spend": { "get": { "x-card": "C132", "operationId": "agentSpendGlance", "tags": [ "Agent rulebook" ], "summary": "See agent charged spending over seven UTC dates", "description": "Read-only; same management or owner/admin auth and account/team scope as the agents list. AGENT_POLICY_ENABLED defaults false; off returns 404. Today and six previous UTC dates, oldest first including zero days. Counts negative usage, tool_call and data_tool ledger entries by settlement time, excluding refunds, holds and estimates. Models use explicit generation links matching key/account; unlinked charges still count in totals. Top model is highest attributed spend, ties by identifier. Last request is latest retained generation time or charged ledger settlement time, including earlier dates and free recorded model calls. No retained data is added. Parent/session spend remains separate. Cache-Control: no-store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7 ], "default": 7 } } ], "responses": { "200": { "description": "Seven-day charged-spend summaries", "content": { "application/json": { "schema": { "type": "object", "required": [ "days", "from", "as_of", "data" ], "properties": { "days": { "type": "integer", "const": 7 }, "from": { "type": "string", "format": "date-time" }, "as_of": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "type": "object", "required": [ "key_hash", "daily", "total_usd", "top_model", "last_request_at" ], "properties": { "key_hash": { "type": "string" }, "daily": { "type": "array", "minItems": 7, "maxItems": 7, "items": { "type": "object", "required": [ "date", "charged_usd" ], "properties": { "date": { "type": "string", "format": "date" }, "charged_usd": { "type": "number", "minimum": 0 } } } }, "total_usd": { "type": "number", "minimum": 0 }, "top_model": { "type": [ "object", "null" ], "required": [ "id", "name", "charged_usd" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "charged_usd": { "type": "number", "minimum": 0 } } }, "last_request_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/approvals/{id}/approve-and-allow": { "get": { "summary": "Preview an approval's ask-first amount change", "description": "B118: management or same-team owner/admin auth as Approve. Inference and session keys refused. Only amount-only approvals for the current own rulebook; playbook followers return 409 playbook_linked with playbook_id and playbook_name. AGENT_POLICY_ENABLED false returns 404; actions require AGENT_GUARD_ENABLED. Returns data.field, before_usd, after_usd, amount_usd and policy_sha256. Preview changes nothing.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exact threshold change; amounts are decimal USD strings." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not pending, not amount-only, rules changed or playbook followed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Approve and allow next time", "description": "B118: same auth and eligibility as GET. In one transaction approves once and saves only approval.above_usd for model calls or actions.approval_above_usd for actions, rounded up to the cent, with the schema version and hash-chained policy_set and approval_approved events. Caps are unchanged. Original single-use retry binding and expiry remain. Changed hash returns 409. Telegram unchanged.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "policy_sha256" ], "properties": { "policy_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "data contains approval (existing approval shape), change (the GET preview), policy (updated rulebook), version (schema version) and sha256 (new policy digest)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not pending, not amount-only, rules changed or playbook followed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/facilitator/supported": { "get": { "tags": [ "Facilitator" ], "operationId": "facilitatorSupported", "summary": "List supported kinds, signers and policy", "description": "FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator. kinds lists x402Version 1 and 2 with scheme exact on eip155:4663 (and the router's v1 name for the chain). policy states custody none, the fee (0 bps during the launch waiver), the minimum settle, gas floats, the relay balance floor, rate limits, the SellerListing EIP-712 types and the screening policy: listings are screened against the OFAC SDN list when SANCTIONS_SCREENING_ENABLED is on; payers and settlements are not screened.", "responses": { "200": { "description": "Supported kinds and policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorSupported" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "facilitator_disabled (ApiError), or for verify and settle facilitator_unavailable in the x402 shape when the relay key is below FACILITATOR_RELAY_FLOOR_WEI; Retry-After is set. Nothing is queued." } } } }, "/facilitator/verify": { "post": { "tags": [ "Facilitator" ], "operationId": "facilitatorVerify", "summary": "Verify an x402 exact payment without moving funds", "description": "FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator. Checks scheme, network, asset (USDG), the recipient, the amount (v1 maxAmountRequired, v2 amount and what the payer accepted), validBefore at least 6 seconds ahead, validAfter, the payer's EIP-712 signature (ECDSA or ERC-1271) over USDG's domain, the nonce unused on chain and in the facilitator's own record, the balance, the minimum settle (payment_below_facilitator_minimum unless the seller's gas float covers it) and, when FACILITATOR_FEE_BPS is above 0, the fee authorization (facilitator_fee_required, invalid_facilitator_fee).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorPaymentRequest" } } } }, "responses": { "200": { "description": "isValid with the payer, or isValid false with an invalidReason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorVerifyResponse" } } } }, "503": { "description": "facilitator_disabled (ApiError), or for verify and settle facilitator_unavailable in the x402 shape when the relay key is below FACILITATOR_RELAY_FLOOR_WEI; Retry-After is set. Nothing is queued." }, "4XX": { "description": "400 for a body it cannot read (invalidReason/errorReason invalid_payload, invalid_payment_requirements or invalid_x402_version) and 429 rate_limited with Retry-After (per caller address, per payer and per payTo), in the same x402 shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorVerifyResponse" } } } } } } }, "/facilitator/settle": { "post": { "tags": [ "Facilitator" ], "operationId": "facilitatorSettle", "summary": "Verify and settle an x402 exact payment", "description": "FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator. Runs every verify check, claims (payer, nonce) and relays transferWithAuthorization from the payer straight to payTo with the facilitator's relay key, which pays the gas. A replay answers success false with invalid_exact_evm_payload_authorization_nonce_used; a relay that fails answers unexpected_settle_error and the unused authorization may be settled again. With a fee, the second authorization is relayed to the treasury after the payment. Each settle gets a signed receipt (kind facilitator.settle) that joins the hourly anchor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorPaymentRequest" } } } }, "responses": { "200": { "description": "success with the transaction, or success false with an errorReason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorSettleResponse" } } } }, "503": { "description": "facilitator_disabled (ApiError), or for verify and settle facilitator_unavailable in the x402 shape when the relay key is below FACILITATOR_RELAY_FLOOR_WEI; Retry-After is set. Nothing is queued." }, "4XX": { "description": "400 for a body it cannot read (invalidReason/errorReason invalid_payload, invalid_payment_requirements or invalid_x402_version) and 429 rate_limited with Retry-After (per caller address, per payer and per payTo), in the same x402 shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorSettleResponse" } } } } } } }, "/facilitator/discovery/resources": { "get": { "tags": [ "Facilitator" ], "operationId": "facilitatorDiscovery", "summary": "List sellers who opted in, in the x402 discovery item shape", "description": "FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator. Listed sellers newest first. accepts is built from the seller's price hint; the seller's own 402 response stays authoritative. A type other than http or another network returns no items.", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "http" ] } }, { "name": "network", "in": "query", "schema": { "type": "string", "example": "eip155:4663" } }, { "name": "tag", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "x402Version", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2 ], "default": 2 } } ], "responses": { "200": { "description": "Discovery items with pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorDiscovery" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "facilitator_disabled (ApiError), or for verify and settle facilitator_unavailable in the x402 shape when the relay key is below FACILITATOR_RELAY_FLOOR_WEI; Retry-After is set. Nothing is queued." } } } }, "/facilitator/sellers": { "post": { "tags": [ "Facilitator" ], "operationId": "facilitatorListSeller", "summary": "Create or update a listing signed by the payTo key", "description": "FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator. The body is the EIP-712 SellerListing message (types in GET /facilitator/supported policy.listing) and its signature by the payTo key (ECDSA or ERC-1271). issuedAt must be within 600 seconds of now; a later signature replaces an earlier one; the first payTo to list a resource owns it (409 resource_taken). A listed payTo on the OFAC SDN list is refused with 403 sanctioned_address. FACILITATOR_LISTINGS_PER_HOUR per payTo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorListingRequest" } } } }, "responses": { "200": { "description": "Listing updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FacilitatorListing" } } } } } }, "201": { "description": "Listing created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FacilitatorListing" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "resource_taken or stale_listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "facilitator_disabled (ApiError), or for verify and settle facilitator_unavailable in the x402 shape when the relay key is below FACILITATOR_RELAY_FLOOR_WEI; Retry-After is set. Nothing is queued." } } } }, "/facilitator/sellers/{id}": { "get": { "tags": [ "Facilitator" ], "operationId": "facilitatorSeller", "summary": "Read a listing and its gas float", "description": "FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fsl_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "The listing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/FacilitatorListing" }, { "type": "object", "properties": { "gasFloat": { "type": [ "object", "null" ], "properties": { "balance": { "type": "string" }, "funded": { "type": "string" }, "debited": { "type": "string" } } } } } ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "facilitator_disabled (ApiError), or for verify and settle facilitator_unavailable in the x402 shape when the relay key is below FACILITATOR_RELAY_FLOOR_WEI; Retry-After is set. Nothing is queued." } } } }, "/facilitator/sellers/{id}/gas-float": { "post": { "tags": [ "Facilitator" ], "operationId": "facilitatorFundGasFloat", "summary": "Top up a seller's gas float", "description": "FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator. Needs FACILITATOR_ETH_USDG and FACILITATOR_TREASURY (503 gas_floats_unavailable otherwise). The body carries an exact paymentPayload to FACILITATOR_TREASURY of at least the minimum settle, from any wallet; it is verified and relayed like any settle and its value is credited to the float. Settles below the minimum are then debited at measured gas times FACILITATOR_GAS_BUFFER_BPS.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fsl_[0-9a-f]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paymentPayload" ], "properties": { "paymentPayload": { "type": "object" } } } } } }, "responses": { "200": { "description": "Settle result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorSettleResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "description": "facilitator_disabled (ApiError), or for verify and settle facilitator_unavailable in the x402 shape when the relay key is below FACILITATOR_RELAY_FLOOR_WEI; Retry-After is set. Nothing is queued." }, "4XX": { "description": "400 for a body it cannot read (invalidReason/errorReason invalid_payload, invalid_payment_requirements or invalid_x402_version) and 429 rate_limited with Retry-After (per caller address, per payer and per payTo), in the same x402 shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorSettleResponse" } } } } } } }, "/facilitator/receipts/{id}": { "get": { "tags": [ "Facilitator" ], "operationId": "facilitatorReceipt", "summary": "Read a settlement receipt and its anchor proof", "description": "FACILITATOR_ENABLED defaults to false; while it is off every /facilitator route answers 503 facilitator_disabled. GET /api/v1/status reports data.facilitator. The COSE_Sign1 receipt (kind facilitator.settle: network, asset, tx, value, pay_to, purpose, x402_version, fee; no payer) signed with the router's receipt key, and the anchor proof once its hour is rooted (null before). ?format=cose returns the raw COSE bytes. Check it with POST /api/v1/receipts/verify.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fst_[0-9a-f]{24}$" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "cose" ] } } ], "responses": { "200": { "description": "The receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitatorReceipt" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "facilitator_disabled (ApiError), or for verify and settle facilitator_unavailable in the x402 shape when the relay key is below FACILITATOR_RELAY_FLOOR_WEI; Retry-After is set. Nothing is queued." } } } }, "/api/v1/statements/{yyyy-mm}": { "get": { "operationId": "getMonthlyStatement", "x-H168-business-details": "Optional business_details=true adds current user-entered business_details beside payload, alg, key_id and sig in data, outside the signed payload. Default response and signature bytes remain unchanged for the same payload. Read-only keys can use this existing allowed statement route. CSV and print/PDF use an unsigned Billed to block; signed JSON downloads omit identity.", "tags": [ "Statements" ], "summary": "Download a signed monthly statement", "description": "V87: STATEMENTS_ENABLED defaults false; disabled route returns 404. Management and owner/admin keys see the account; ordinary and session keys see only their own attributed movements labelled scope=key. Exact USDG decimal strings reconcile to the ledger in one snapshot: opening + deposits + refunds - usage - separate fees + other changes = closing. Usage groups reconcile to usage. UTC month; usage by settlement time, calls by generation time. Current month is so_far. Months before account creation and future months return 404. Holds, external payments and embedded usage fees are not added to totals. Canonical payload JSON is signed with the existing receipt Ed25519 key and key_id; verify with published receipt keys. Print the account-shell HTML view for PDF. No new storage.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "business_details", "in": "query", "description": "H168: include unsigned current business identity outside payload; default omits it.", "schema": { "type": "boolean", "default": false } }, { "name": "yyyy-mm", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json" ], "default": "json" } } ], "responses": { "200": { "description": "Signed statement with Cache-Control: no-store", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "payload", "alg", "key_id", "sig" ], "properties": { "business_details": { "description": "H168: present only with business_details=true, outside the signature.", "oneOf": [ { "$ref": "#/components/schemas/BusinessDetails" }, { "type": "null" } ] }, "alg": { "type": "string", "enum": [ "Ed25519" ] }, "key_id": { "type": "string" }, "sig": { "type": "string", "description": "Base64 signature of canonical payload JSON" }, "payload": { "type": "object", "description": "anyroute.statement.v1: month, currency, UTC bounds, generated_at, account_created_at, scope, key_hash, opening_balance, deposits, refunds, usage, fees, other_changes, closing_balance, calls, usage_by_model, usage_by_key_agent, usage_by_lane, movements_by_kind, reconciliation, limits. Money and calls are decimal strings. Group ids can be null." } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/refunds": { "get": { "operationId": "listRefunds", "tags": [ "Receipts" ], "summary": "List make-good refunds", "description": "V6 R: MAKEGOOD_ENABLED defaults to false; the route returns 404 while it is off (GET /api/v1/status reports makegood.enabled). Deterministic refunds decided from facts recorded when a call is served or fails: upstream_failure (a per-call payment for a request no provider served, 100%, on-chain), fallback_price (failover to a pricier provider, the price difference), truncated_stream (billed output tokens never delivered), structured_output (the JSON repair answer still does not parse, 100% of the repair call) and unattested_lane (100% plus a host strike). Capped by what the ledger charged; at most one refund per call or payment. Management and owner/admin keys see the account, other keys their own calls; a per-call wallet payer can read its refunds with X-Wallet-Auth signed over the empty body. Each issued refund has a signed v1 receipt of kind refund at GET /api/v1/receipts/{id} naming original_receipt_id. Cache-Control: no-store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1 to 100, default 50", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Refunds, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rule": { "type": "string", "enum": [ "upstream_failure", "fallback_price", "truncated_stream", "structured_output", "unattested_lane" ] }, "status": { "type": "string", "enum": [ "pending", "issued" ] }, "amount": { "type": "string", "description": "Refund in USD, exact decimal" }, "charged": { "type": "string" }, "currency": { "type": "string" }, "generation_id": { "type": [ "string", "null" ] }, "receipt_id": { "type": [ "string", "null" ] }, "receipt_url": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "strike": { "type": "boolean" }, "evidence": { "type": "object" }, "settlement": { "type": [ "string", "null" ], "enum": [ "credit", "onchain", null ] }, "onchain": { "type": [ "object", "null" ], "properties": { "usdg_units": { "type": "string" }, "status": { "type": "string", "enum": [ "owed", "batched", "paid" ] } } }, "detected_at": { "type": "string" }, "issued_at": { "type": [ "string", "null" ] } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List owned destinations without secrets", "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at anyroute.tech. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List owned destinations without secrets" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a destination and reveal its signing secret once", "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at anyroute.tech. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Create a destination and reveal its signing secret once" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "spend.alert", "agent.alert", "approval.requested", "approval.decided", "deposit.credited", "agreement.funded", "agreement.disputed", "agreement.ruled", "host.status_changed", "refund.issued" ] } } }, "required": [ "webhook_url", "events" ], "additionalProperties": false } } } } } }, "/api/v1/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "summary": "Update event subscriptions", "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at anyroute.tech. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Update event subscriptions" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "spend.alert", "agent.alert", "approval.requested", "approval.decided", "deposit.credited", "agreement.funded", "agreement.disputed", "agreement.ruled", "host.status_changed", "refund.issued" ] } } }, "required": [ "events" ], "additionalProperties": false } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Remove an independent destination", "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at anyroute.tech. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Remove an independent destination" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhooks/{id}/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate and reveal a replacement signing secret once", "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at anyroute.tech. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Rotate and reveal a replacement signing secret once" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhooks/{id}/revoke": { "post": { "tags": [ "Webhooks" ], "summary": "Erase signing secret and stop future delivery", "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at anyroute.tech. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Erase signing secret and stop future delivery" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Read the last 100 attempt metadata entries", "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at anyroute.tech. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Read the last 100 attempt metadata entries" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Queue an endpoint check event", "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at anyroute.tech. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.", "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Queue an endpoint check event" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Limit or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/activity": { "get": { "x-j182-trace-a-charge": "Activity links retain kind, model, key (agent hash), project, from inclusive and to exclusive in the dashboard URL. Optional basis=charges selects posted negative usage/tool_call/data_tool ledger entries by settlement time, with unchanged account/key/session visibility. charge_kind=usage restricts to statement usage; charge_kind=rulebook to usage/tool_call. paid=true selects negative amounts; lane selects coalesced recorded lane (unknown for missing); missing_model=true or missing_project=true selects absent metadata (incompatible with the corresponding value filter). All filters bind cursors and CSV. Missing signed call receipts/models remain null; no new storage or flag. See /docs/#trace-a-charge. J182", "operationId": "listActivity", "summary": "List account activity", "description": "Calls (with receipt ids and verify links), agent approvals and rule decisions, alerts, deposits and balance changes, and agreement events, newest first, in one item shape with exact USDG amounts. A key sees its own activity; management, owner and admin keys see the account within their team boundaries. format=csv returns this page as CSV with X-Next-Cursor when another page exists.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "basis", "in": "query", "schema": { "type": "string", "enum": [ "charges" ] } }, { "name": "charge_kind", "in": "query", "schema": { "type": "string", "enum": [ "usage", "rulebook" ] } }, { "name": "paid", "in": "query", "schema": { "type": "string", "enum": [ "true" ] } }, { "name": "missing_model", "in": "query", "schema": { "type": "string", "enum": [ "true" ] } }, { "name": "missing_project", "in": "query", "schema": { "type": "string", "enum": [ "true" ] } }, { "name": "lane", "in": "query", "schema": { "type": "string", "maxLength": 64 } }, { "name": "project", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]{1,48}$" }, "description": "C134: lowercase-matched call project. Activity JSON adds project on tagged calls; CSV includes a project column. This filter selects calls only." }, { "name": "kind", "in": "query", "required": false, "description": "call, approval, alert, deposit, agreement, policy, balance or topup", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "64-hex key hash to filter by", "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "description": "Model id", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "ISO 8601 timestamp with timezone, inclusive", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "ISO 8601 timestamp with timezone, exclusive", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 100, default 50", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json (default) or csv", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/inbox": { "get": { "x-h173-inbox-filters": "Optional kinds filters by comma-separated groups (approvals, agents, money, security, models, other) or individual item kinds. Unknown kinds map to Other. Filtered responses add kind_counts with integer counts for all six groups before filtering; data and unread count cover the selection. Omitted kinds leaves the response unchanged. Existing since, visibility, notification preferences and capped source limits apply. Browser mark-all uses the full as_of snapshot with POST /api/v1/inbox/seen, stores only the returned time under seen_scope, and can restore the prior bookmark for 10 seconds unless replaced by a newer time. Pending approvals remain actionable even when read in the browser. No server persistence or cross-browser sync. H173.", "operationId": "listInbox", "x-approval-context": { "description": "J185: approval items the caller may decide include optional approval_context string lines when AGENT_APPROVAL_CONTEXT_ENABLED (default false); identical builder and limits to AgentApproval.approval_context.", "schema": { "type": "array", "items": { "type": "string" } } }, "x-h169-incident-alerts": "When STATUS_INCIDENT_NOTICES_ENABLED (default false) is on, opted-in management inboxes include status_incidents items with id, at (public update time), kind, title (status and public incident title), status null, href /status/ and unread true. Both channels default off in account notification settings. Ordinary and session keys receive none. Unique kv claims record each change once across workers; notices last up to 90 days. Telegram uses linked management principals and quiet hours. No inference text is included.", "x-d141-quiet-agent-alerts": "With QUIET_AGENT_ALERTS_ENABLED (default false) and AGENT_POLICY_ENABLED, account-management and current owning-team owner/admin inboxes include quiet-agent items; ordinary and session keys receive none. Fields: id (random quiet notice id), at (notice timestamp), kind (quiet-agent), title (readable agent name, window and last charged call or Guard decision time), status (quiet), href (/agents/), key_label (current name), unread (true). since and as_of filtering apply, with at most 100 items returned and capped when more exist. History is bounded to 100 per agent and 90 days. Off contributes no items. D141.", "x-c133-price-notices": "With PRICE_NOTICES_ENABLED (default false), active account management keys excluding sessions receive price_notice items for catalogue changes of at least 1% to models used by the account in the last 30 days. Fields: id, at, kind, title, model (null for grouped changes), status (null), href (/models/), unread. Existing since filtering applies. First snapshot is silent. At most five items per account per UTC day: four individual and one grouped item whose count can update. Ordinary keys, sessions and team-only administrators do not see account-wide price notices. Rows are retained for 30 UTC days while enabled. No new endpoint or authentication change.", "summary": "List items that need attention", "description": "Pending approvals with their expiry, alerts, deposits, key auto top-ups, agreement events and status updates for hosts the account operates, under the same access rules as /api/v1/activity. Pass since (the seen time the browser keeps) to mark newer items. B119: when LOW_BALANCE_ALERTS_ENABLED is true, account-scope inboxes also include low-balance crossings with kind low_balance, id, at, title, amount (decimal USD balance), status null, href /dashboard/#money, and unread. Session and ordinary key-scope inboxes cannot see these account alerts.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "kinds", "in": "query", "required": false, "description": "H173. Comma-separated group names or item kinds, e.g. approvals,money or approval,deposit. Empty or malformed values return 400. Counts describe the bounded authorized snapshot before filtering.", "schema": { "type": "string", "maxLength": 512, "pattern": "^[a-z][a-z_-]*(?:,[a-z][a-z_-]*)*$" } }, { "name": "since", "in": "query", "required": false, "description": "ISO 8601 seen time, not in the future", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind_counts": { "type": "object", "description": "H173: present only when kinds is supplied; counts of returned authorized items before kind filtering, after since and source limits.", "required": [ "approvals", "agents", "money", "security", "models", "other" ], "properties": { "approvals": { "type": "integer", "minimum": 0 }, "agents": { "type": "integer", "minimum": 0 }, "money": { "type": "integer", "minimum": 0 }, "security": { "type": "integer", "minimum": 0 }, "models": { "type": "integer", "minimum": 0 }, "other": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } } } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-D138-security-alerts": "When SECURITY_ALERTS_ENABLED: security items have kind security, id, at, title, status null, href /dashboard/#settings and unread. Account management keys see all account security items; team owners/admins see only their team; session and ordinary keys see none. since filters event time. One item per recorded event, including changes by the current key. Claimed items expire after 90 days while the worker is enabled.", "x-d136-scheduled-prompts": "When SCHEDULED_PROMPTS_ENABLED is true, owner inboxes include finished retained runs visible in their paying-key team scope: kind schedule, id, at, title (name and first 300 reply characters or failure code), status, href to the authenticated saved result, unread. Inference and session keys never receive these items. Deleting the schedule removes its inbox items.", "x-j184-weekly-summary": "Weekly summary items optionally add sections, an array of text and href pairs linking reliability and estimated savings to /dashboard/#insights, retained model-watch changes to /models/, agent caps and undecided expired approvals to /agents/. Empty sections are omitted. Existing management auth, weekly_summary notification preferences and WEEKLY_SUMMARY_ENABLED (default false) apply. No new endpoint or persistence." } }, "/api/v1/inbox/seen": { "post": { "operationId": "markInboxSeen", "summary": "Return a seen time for the displayed inbox", "description": "Validates the key and returns the seen time to keep in the browser. Nothing is stored on the server.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "through", "in": "query", "required": true, "description": "ISO 8601 time of the displayed snapshot, not in the future", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/network/stats": { "get": { "operationId": "networkStats", "summary": "Read network statistics", "description": "Present only with NETWORK_STATS_ENABLED (default false). Public read-only snapshots cached at most 30 seconds; HTTP freshness is limited to remaining snapshot lifetime. Host counts include only network hosts. Attested capacity requires fresh successful hardware attestation and admission evidence. Public-lane token ranges use 100,000-token buckets, not differential privacy, from retained generation records only. Private-lane host totals are unavailable: existing DP counters have no host dimension or 7/30-day history. Null means absent records or a disabled optional source. Bond amounts retain index freshness. Waitlist counts express interest only.", "security": [], "responses": { "200": { "description": "Network snapshot", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=, must-revalidate" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NetworkStats" } } } } } }, "404": { "$ref": "#/components/responses/NotFound", "description": "Network statistics are disabled" }, "503": { "description": "Aggregate source unavailable; no stale response is served", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/agreements": { "get": { "tags": [ "Agreements" ], "summary": "List wallet-linked party agreements; cursor and next_cursor paginate 50 rows.", "description": "AGENT_AGREEMENTS_ENABLED defaults false; unset escrow/oracle addresses keep this off. Router-run jury uses attested models only; A complete signed hung tally enables a panel; failed or abstaining votes remain unresolved until a valid tally or expiry. Oracle signer keys certify authorization, not model execution. Rulings default to dry run. Contracts are not deployed at anyroute.tech yet. Router reads evidence in memory.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agreement result" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Evidence window, limit or retention constraint" }, "413": { "description": "Evidence exceeds cap" } }, "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } } ] } }, "/api/v1/agreements/prepare": { "post": { "tags": [ "Agreements" ], "summary": "Check inherited agreement rulebooks and return unsigned USDG escrow calldata; payer signs its own transaction.", "description": "AGENT_AGREEMENTS_ENABLED defaults false; unset escrow/oracle addresses keep this off. Router-run jury uses attested models only; A complete signed hung tally enables a panel; failed or abstaining votes remain unresolved until a valid tally or expiry. Oracle signer keys certify authorization, not model execution. Rulings default to dry run. Contracts are not deployed at anyroute.tech yet. Router reads evidence in memory.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agreement result" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Evidence window, limit or retention constraint" }, "413": { "description": "Evidence exceeds cap" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "payee", "milestone_amounts_usdg_units", "terms_hash", "deadline" ], "properties": { "payee": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "milestone_amounts_usdg_units": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" } }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "deadline": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "Future Unix timestamp in seconds; escrow reviewWindow is immutable." } } } } } } } }, "/api/v1/agreements/{id}": { "get": { "tags": [ "Agreements" ], "summary": "Read canonical agreement milestone, both parties evidence and router-signed jury statement with per-model verdicts and receipt links.", "description": "AGENT_AGREEMENTS_ENABLED defaults false; unset escrow/oracle addresses keep this off. Router-run jury uses attested models only; A complete signed hung tally enables a panel; failed or abstaining votes remain unresolved until a valid tally or expiry. Oracle signer keys certify authorization, not model execution. Rulings default to dry run. Contracts are not deployed at anyroute.tech yet. Router reads evidence in memory.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agreement result" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Evidence window, limit or retention constraint" }, "413": { "description": "Evidence exceeds cap" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})[.](0|[1-9][0-9]?)$" } } ] } }, "/api/v1/agreements/{id}/evidence": { "post": { "tags": [ "Agreements" ], "summary": "Upload capped JSON or JSON-encoded text; stored hash plus APP_SECRET-encrypted content, readable by both parties and the router.", "description": "AGENT_AGREEMENTS_ENABLED defaults false; unset escrow/oracle addresses keep this off. Router-run jury uses attested models only; A complete signed hung tally enables a panel; failed or abstaining votes remain unresolved until a valid tally or expiry. Oracle signer keys certify authorization, not model execution. Rulings default to dry run. Contracts are not deployed at anyroute.tech yet. Router reads evidence in memory.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agreement result" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Evidence window, limit or retention constraint" }, "413": { "description": "Evidence exceeds cap" }, "201": { "description": "Evidence hash and dispute identity" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})[.](0|[1-9][0-9]?)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } } }, "delete": { "tags": [ "Agreements" ], "summary": "Delete own evidence after canonical resolution plus retention with a fresh index.", "description": "AGENT_AGREEMENTS_ENABLED defaults false; unset escrow/oracle addresses keep this off. Router-run jury uses attested models only; A complete signed hung tally enables a panel; failed or abstaining votes remain unresolved until a valid tally or expiry. Oracle signer keys certify authorization, not model execution. Rulings default to dry run. Contracts are not deployed at anyroute.tech yet. Router reads evidence in memory.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agreement result" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Evidence window, limit or retention constraint" }, "413": { "description": "Evidence exceeds cap" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})[.](0|[1-9][0-9]?)$" } } ] } }, "/api/v1/network/burns": { "get": { "summary": "Network fee swaps and burns", "description": "Public aggregate pico-USD fees, burned ANYR units and up to 50 recent swap and dead-address transfer transactions with explorer links. Available with the keeper disabled. Individual host invoice amounts are omitted.", "responses": { "200": { "description": "Aggregate totals, enabled status, fee_bps, conversion dust, ANYR decimals and recent transactions", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/agents": { "get": { "operationId": "listAgents", "tags": [ "Agent rulebook" ], "summary": "List account agent keys", "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Includes effective rulebooks, kill state, rolling spend plus reservations and caps. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "stopped_until": { "type": "string", "format": "date-time", "description": "B117: Optional timed stop deadline; alerts retain the deadline captured at the stop and include it in webhook and Telegram delivery." } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/me": { "get": { "operationId": "agentMe", "tags": [ "Agent rulebook" ], "summary": "Read the calling key’s rulebook", "description": "Includes own and inherited parent rulebooks, remaining rolling caps and kill state. Optional autonomy reports rung, since, clean_requests, last_clean_at, caps_multiplier and next (rung, after_days, clean_requests, caps_multiplier, elapsed_days, days_remaining, requests_remaining), or null at the top. effective_caps scales only spending caps. Progress resets on selected deny, kill or recorded breaker events and on rulebook saves. A session and its parent must both pass. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "stopped_until": { "type": "string", "format": "date-time", "description": "B117: Effective timed stop deadline; omitted when running or any stopped inherited policy has no deadline. Also reported by MCP anyroute_agent_rules. Each timed policy in policies reports its own deadline." } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/approvals": { "get": { "tags": [ "Agent rulebook" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Approval list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentApproval" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Approval is no longer pending" } }, "operationId": "listAgentApprovals", "summary": "List principal-visible approvals", "description": "AGENT_POLICY_ENABLED defaults false; off returns 404. Management key or same-account team owner/admin. Up to 100 newest rows. Pending by default. Expiry ends validity but does not delete approval rows.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "denied", "expired", "used" ], "default": "pending" } } ] } }, "/api/v1/agents/approvals/{id}": { "get": { "tags": [ "Agent rulebook" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Status only", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "status", "expires_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired", "used" ] }, "expires_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Approval is no longer pending" } }, "operationId": "getAgentApprovalStatus", "summary": "Poll approval status", "description": "Principal or the requesting key; returns only id, status and expires_at. Off returns 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/agents/approvals/{id}/approve": { "post": { "tags": [ "Agent rulebook" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Approval result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Approval is no longer pending" } }, "operationId": "approveAgentApproval", "summary": "Approve a pending approval", "description": "Management key or same-account team owner/admin of the requesting key. Session and ordinary agent keys cannot decide. Records the principal key hash and a chained event. Expired or completed rows return 409. Off returns 404. Retry inference with X-Agent-Approval: after approval; it is single-use, binds key/model/lane/tools/output token limit, and permits estimated cost no greater than the approved ceiling. All rulebook restrictions still apply. AGENT_APPROVAL_TTL_S defaults to 900 seconds from request time.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/agents/approvals/{id}/deny": { "post": { "tags": [ "Agent rulebook" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Approval result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Approval is no longer pending" } }, "operationId": "denyAgentApproval", "summary": "Deny a pending approval", "description": "Management key or same-account team owner/admin of the requesting key. Session and ordinary agent keys cannot decide. Records the principal key hash and a chained event. Expired or completed rows return 409. Off returns 404. Retry inference with X-Agent-Approval: after approval; it is single-use, binds key/model/lane/tools/output token limit, and permits estimated cost no greater than the approved ceiling. All rulebook restrictions still apply. AGENT_APPROVAL_TTL_S defaults to 900 seconds from request time.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/agents/check": { "post": { "operationId": "checkAgentPolicy", "tags": [ "Agent rulebook" ], "summary": "Evaluate an Intent without recording it", "description": "Calling API key. Returns a deterministic decision with no event writes or automatic kill. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentDecision" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentIntent" } } } } } }, "/api/v1/agents/{key_hash}/policy": { "get": { "operationId": "getAgentPolicy", "tags": [ "Agent rulebook" ], "summary": "Read a rulebook", "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentPolicyResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "operationId": "putAgentPolicy", "tags": [ "Agent rulebook" ], "summary": "Set a rulebook", "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Replaces the specification while preserving existing kill state. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentPolicyResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPolicy" } } } } }, "delete": { "operationId": "deleteAgentPolicy", "tags": [ "Agent rulebook" ], "summary": "Remove a rulebook", "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Removes this key’s own rulebook; a session’s inherited parent rulebook still applies. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/playbooks": { "get": { "operationId": "listPlaybooks", "tags": [ "Playbooks" ], "summary": "List playbooks", "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. A management key sees every playbook of the account; a team owner or admin sees its team's and the account-wide ones. Each lists how many keys follow it and the following keys the caller manages. Off (AGENT_POLICY_ENABLED false) returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Playbook" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createPlaybook", "tags": [ "Playbooks" ], "summary": "Create a playbook", "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. A team owner or admin creates a playbook for its own team; a management key creates an account-wide one, or one for a team it owns with team_id. Version starts at 1. Off (AGENT_POLICY_ENABLED false) returns 404.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybookInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Playbook" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "playbook_name_taken or playbook_limit_reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/playbooks/{id}": { "get": { "operationId": "getPlaybook", "tags": [ "Playbooks" ], "summary": "Read a playbook", "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. Adds the latest 50 recorded changes, newest first. Off (AGENT_POLICY_ENABLED false) returns 404.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Playbook" }, { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybookChange" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updatePlaybook", "tags": [ "Playbooks" ], "summary": "Change a playbook", "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. Account-wide playbooks change only with a management key. New rules raise version by one and are copied, in the same transaction, to every key that follows the playbook, which uses them from its next request. Unchanged name and rules change nothing (changed false). For a team the change is in the team audit log, and a change of rules is in the inbox of the team's owners and admins. Off (AGENT_POLICY_ENABLED false) returns 404.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybookUpdate" } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Playbook" }, { "type": "object", "properties": { "changed": { "type": "boolean" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "playbook_name_taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "operationId": "deletePlaybook", "tags": [ "Playbooks" ], "summary": "Delete a playbook", "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. Refused with 409 playbook_followed and metadata.followers while keys follow the playbook, unless unlink=copy: each following key then keeps the playbook's rules as its own rulebook. Off (AGENT_POLICY_ENABLED false) returns 404.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "unlink", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "copy" ] } } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "deleted", "unlinked" ], "properties": { "id": { "type": "string" }, "deleted": { "const": true }, "unlinked": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "playbook_followed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/agents/{key_hash}/playbook": { "post": { "operationId": "followPlaybook", "tags": [ "Playbooks" ], "summary": "Follow a playbook, or stop following", "description": "Management key or owner/admin of the target key's account and team, with the same permissions as editing that key. With a playbook_id, the key's rules become that playbook's current rules (its stop state is kept); a team playbook takes keys of that team only (409 playbook_team_mismatch). With null, the key stops following and keeps the playbook's current rules as its own. While a key follows a playbook, PUT and DELETE on its own rulebook answer 409 playbook_linked. Off (AGENT_POLICY_ENABLED false) returns 404.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybookFollow" } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlaybookFollowResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "playbook_team_mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/agents/{key_hash}/kill": { "post": { "operationId": "killAgent", "tags": [ "Agent rulebook" ], "summary": "Stop an agent", "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. A committed kill is read on the next request by every replica, without policy caching. Requires an existing rulebook. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentPolicyResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "until": { "type": "string", "format": "date-time", "description": "B117: Optional ISO time with timezone, future and at most 30 days ahead; omitted stops until manual Resume. The next enforcement check after expiry clears the stop atomically and appends a resume event with reason scheduled." }, "reason": { "type": "string", "maxLength": 160 } } } } } } } }, "/api/v1/agents/{key_hash}/resume": { "post": { "operationId": "resumeAgent", "tags": [ "Agent rulebook" ], "summary": "Resume an agent", "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Clears kill state without changing the specification. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentPolicyResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/agents/{key_hash}/replay": { "post": { "operationId": "replayAgentPolicy", "tags": [ "Agent rulebook" ], "summary": "Replay a draft rulebook on the last days of recorded activity", "description": "Same permissions as setting that key’s rulebook. Evaluates the draft against up to 5,000 of the key’s recorded calls (its own and its session keys’: model, lane, cost, tokens and time, never the text) and Agent Guard checks in the window, oldest first, with running caps, calls per hour, windows, breakers, autonomy and Stop. Read only: nothing is saved, charged or changed. Ten a minute per calling key. What the record cannot tell is listed in notes. Off returns 404.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "policy" ], "properties": { "policy": { "$ref": "#/components/schemas/AgentPolicy" }, "days": { "type": "integer", "minimum": 1, "maximum": 7, "default": 7 } } } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentReplay" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/agents/{key_hash}/events": { "get": { "operationId": "agentEvents", "tags": [ "Agent rulebook" ], "summary": "Read policy events", "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Newest first, 50 per page. next_cursor is a before-id cursor. Metadata-only hash chain; 90-day retention when the cleanup worker runs. Off returns 404.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ] } }, "/api/v1/network/hosts": { "post": { "summary": "Apply or re-apply a network host using existing wallet authentication", "description": "Available only with NETWORK_HOSTS_ENABLED=true; default false. See /docs/#network-host-signup. Policy offer terms enable shadow offers during probation; signup does not activate payouts. Scheduled renewal checks the current signed policy without promoting hosts to live. Failed attestation blocks selection; policy refusal rejects the host and disables offers. Admission records attested retention with the policy version and leaves jurisdiction, legal hold and training use undeclared; rejection clears the disclosure profile.", "responses": { "200": { "description": "Current record", "content": { "application/json": { "schema": { "type": "object", "required": [ "provider_id", "status", "reasons", "dashboard" ], "properties": { "provider_id": { "type": "string" }, "status": { "type": "string", "enum": [ "probation", "rejected", "pending" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "dashboard": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "201": { "description": "New host record", "content": { "application/json": { "schema": { "type": "object", "required": [ "provider_id", "status", "reasons", "dashboard" ], "properties": { "provider_id": { "type": "string" }, "status": { "type": "string", "enum": [ "probation", "rejected", "pending" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "dashboard": { "type": "string" } } } } } } }, "security": [ { "WalletAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "endpoint", "payout_address", "models" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "endpoint": { "type": "string", "format": "uri", "description": "Sidecar root HTTPS URL. HTTP is recorded as rejected." }, "payout_address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "models": { "type": "array", "minItems": 1, "maxItems": 8, "uniqueItems": true, "items": { "type": "string", "maxLength": 160 } }, "contact": { "type": "string", "maxLength": 120 } } } } } } } }, "/api/v1/network/hosts/{provider_id}/status": { "get": { "summary": "Read public network host admission status", "description": "Available only with NETWORK_HOSTS_ENABLED=true; default false. See /docs/#network-host-signup. Policy offer terms enable shadow offers during probation; signup does not activate payouts.", "responses": { "200": { "description": "Current record", "content": { "application/json": { "schema": { "type": "object", "required": [ "provider_id", "status", "reasons", "attested", "probation_until", "weight" ], "properties": { "provider_id": { "type": "string" }, "status": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "attested": { "type": "boolean" }, "probation_until": { "type": [ "string", "null" ], "format": "date-time" }, "weight": { "type": "number", "minimum": 0, "maximum": 1, "description": "Current network selector multiplier, rounded to two decimals; highest across eligible model offers, not a traffic percentage. Probation starts at 0.1 and health can reduce it. Zero with hosting off, refusal, stale or failed attestation, unhealthy evidence, or no eligible offers. Status route is absent when hosting is disabled." } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/network/hosts/{provider_id}/credential": { "put": { "summary": "Supply an operator-generated sidecar inference credential", "description": "Available only with NETWORK_HOSTS_ENABLED=true; default false. See /docs/#network-host-signup. Policy offer terms enable shadow offers during probation; signup does not activate payouts.", "responses": { "200": { "description": "Current record", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_id": { "type": "string" }, "credential_configured": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "WalletAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "provider_id", "api_key" ], "properties": { "provider_id": { "type": "string", "description": "Signed provider ID must match path." }, "api_key": { "type": "string", "minLength": 16, "maxLength": 500, "writeOnly": true } } } } } }, "parameters": [ { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/agents/{key_hash}/ledger": { "get": { "operationId": "agentLedger", "tags": [ "Agent rulebook" ], "summary": "Read activity and receipt ledger", "description": "Principal only; same account/team permissions as editing this key. AGENT_POLICY_ENABLED defaults false; off returns 404. from inclusive, to exclusive ISO timestamps. Newest first, at most 100 rows; opaque next_cursor. JSON data.rows and data.totals_per_day (full range, UTC); CSV streams this page with X-Next-Cursor. Correlated rows group policy events and exact generation charges/tokens, receipt_id, verify_url, receipts array, approval_id only if used, policy_sha256 and policy_sha256s. Denials charge zero. Unlinked historical events/generations remain separate; associations are not inferred. Policy events/links have 90-day retention while cleanup runs. Errors before evaluation or generation creation are absent. No prompt or answer text. Router enforcement through AnyRoute only, no on-chain enforcement. Verify links require using the existing checker.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Bounded request page and full-range daily totals, or a CSV page", "headers": { "X-Next-Cursor": { "description": "CSV continuation cursor", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "object", "required": [ "rows", "totals_per_day" ], "properties": { "rows": { "type": "array", "maxItems": 100, "items": { "type": "object" } }, "totals_per_day": { "type": "array", "items": { "type": "object" } } } }, "next_cursor": { "type": [ "string", "null" ] } } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/me/ledger": { "get": { "operationId": "agentSelfLedger", "tags": [ "Agent rulebook" ], "summary": "Read activity and receipt ledger", "description": "Calling key only, including session keys. AGENT_POLICY_ENABLED defaults false; off returns 404. from inclusive, to exclusive ISO timestamps. Newest first, at most 100 rows; opaque next_cursor. JSON data.rows and data.totals_per_day (full range, UTC); CSV streams this page with X-Next-Cursor. Correlated rows group policy events and exact generation charges/tokens, receipt_id, verify_url, receipts array, approval_id only if used, policy_sha256 and policy_sha256s. Denials charge zero. Unlinked historical events/generations remain separate; associations are not inferred. Policy events/links have 90-day retention while cleanup runs. Errors before evaluation or generation creation are absent. No prompt or answer text. Router enforcement through AnyRoute only, no on-chain enforcement. Verify links require using the existing checker.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Bounded request page and full-range daily totals, or a CSV page", "headers": { "X-Next-Cursor": { "description": "CSV continuation cursor", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "object", "required": [ "rows", "totals_per_day" ], "properties": { "rows": { "type": "array", "maxItems": 100, "items": { "type": "object" } }, "totals_per_day": { "type": "array", "items": { "type": "object" } } } }, "next_cursor": { "type": [ "string", "null" ] } } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/{key_hash}/alerts": { "get": { "operationId": "agentAlerts", "tags": [ "Agent rulebook" ], "summary": "Read owner alerts", "description": "AGENT_POLICY_ENABLED defaults false; off returns 404. Same principal permissions as editing the key. Newest 100 entries per account, filtered to this key, retained up to 90 days. Opt in with alerts: {}. Rolling cap percentages count charged spend plus reservations, with one notice per threshold per window-duration cooldown. Repeated denials, kills and new approvals add entries. Reuses enabled Spend Watch webhooks (currently unsigned) and authorized Telegram links; email has no account destination. Without a selected linked channel delivery becomes feed_only. Worker delivery every minute, 10 notices/account/minute, up to 20 destinations/channel and three attempts five minutes apart. At-least-once delivery; a crash may repeat a notice. No prompt or answer text. Router enforcement for AnyRoute requests only, no on-chain enforcement.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Alert feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "stopped_until": { "type": "string", "format": "date-time", "description": "B117: Optional timed stop deadline; alerts retain the deadline captured at the stop and include it in webhook and Telegram delivery." } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/hosts": { "get": { "tags": [ "Hosts" ], "operationId": "listHosts", "summary": "List public hosts with a hardware verification record", "description": "Available only with HOST_DASHBOARD_ENABLED=true (default false). Includes stale or suspended hardware hosts, labelled by their current verification status; excludes applications, unverified providers and development-only evidence. No payout settings or exact earnings.", "security": [], "responses": { "200": { "description": "Public host fields; Cache-Control: public, max-age=30.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HostPublic" } } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/hosts/{providerId}": { "get": { "tags": [ "Hosts" ], "operationId": "getHost", "summary": "Read one host’s evidence and invoice band", "description": "With NETWORK_BONDS_ENABLED, data.bond contains host_id, contract, chain_id, asset, decimals, matched_operator, amount_units, active_units, unbonding {amount_units, available_at}, delisted, indexed_block, fresh, checked_at and slashes [{id, host_id, amount_units, reason, evidence_root, executable_at, dispute_hash, status, transactions [{event, hash, url}]}]. Amounts are decimal base-unit strings. Curated hosts have null bonds. Available only with HOST_DASHBOARD_ENABLED=true (default false). Reuses existing attestation, measurements, proof-time and host-root records. Hardware evidence and recorded measurements do not establish build admission approval, source equivalence or prompt handling. Detail responses always use Cache-Control: no-store and Vary: X-Wallet-Auth. Earnings are lifetime settlement invoice totals after provider fees, including paid invoices and excluding the open hour. USDG units have six decimal places.", "security": [], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Wallet-Auth", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional operator view: address:unixSeconds:personal_sign_signature over anyroute:unixSeconds:sha256(scope), where scope is exactly GET /api/v1/hosts/{encodeURIComponent(providerId)}. Uses existing walletAuth five-minute validity and replay protection. The recovered wallet must equal providers.operator, case-insensitively. This signature authorizes no payment." } ], "responses": { "200": { "description": "Public evidence with coarse bands; operator fields present only for the signed host operator.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/HostDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "description": "Existing evidence endpoint could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/models": { "get": { "tags": [ "Models" ], "operationId": "listModels", "summary": "List public live models", "parameters": [ { "name": "health", "in": "query", "required": false, "description": "E150: recent adds measured performance for eligible funded routes; omitted by default. No key required. Alias: GET /v1/models?health=recent.", "schema": { "type": "string", "enum": [ "recent" ] } }, { "name": "supported_parameters", "in": "query", "required": false, "description": "Comma-separated capabilities to require.", "schema": { "type": "string" } }, { "name": "lane", "in": "query", "required": false, "description": "public (default) lists every live model. attested lists only models with at least one endpoint served under attested retention with a fresh attestation right now. unlinkable lists the same models where the router serves that lane, through Oblivious HTTP or over its Tor onion service (otherwise 501).", "schema": { "type": "string", "enum": [ "public", "attested", "unlinkable" ], "default": "public" } }, { "name": "variant", "in": "query", "required": false, "description": "Comma-separated variants to keep: mainstream, native_low_refusal, abliterated. A restricted variant (native_low_refusal, abliterated) is listed only while an attested provider whose attestation reports the in-enclave classifier serves it, and only such endpoints are counted for it.", "schema": { "type": "string", "examples": [ "abliterated,native_low_refusal" ] } }, { "name": "output_modalities", "in": "query", "required": false, "description": "Comma-separated output modalities to keep (text, embeddings, rerank, ...); a model is kept when it outputs any of them. all, or unset, keeps every model.", "schema": { "type": "string", "examples": [ "rerank" ] } } ], "responses": { "200": { "description": "Models matching the requested capabilities.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "501": { "$ref": "#/components/responses/LaneNotAvailable" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/chat/completions": { "post": { "tags": [ "Chat" ], "operationId": "createChatCompletion", "summary": "Create a chat completion", "description": "Supports standard JSON responses and Server-Sent Events when stream is true. A model must support requested capabilities such as tools or response_format. Auth may use a bearer key, wallet authentication, or the per-call payment flow. A 402 response can contain a quote; follow its payment instructions before retrying the exact request. When the router has x402 enabled, the 402 body is also an x402 v1 payment requirement (x402Version, accepts) and the PAYMENT-REQUIRED header carries the same requirement as x402 v2: sign the exact-scheme USDG authorization and retry with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2); the paid response carries the settlement in X-PAYMENT-RESPONSE and PAYMENT-RESPONSE. If that answer is lost, the same request with the same payment and a PAYMENT-RECOVERY signature gets the kept answer again, byte for byte, without a second payment. Two opt-in modes run several billed calls for one request and are off unless the router enables them: model anyroute/council (a panel of models plus a judge; see the council field) and verify \"dual\" (the same request to two providers; see the verification field). Both are non-streaming only. Where the router enables blind tokens, Authorization: PrivateToken token= pays with one token instead of a key (see the Blind tokens tag): the call is charged to a pooled account, the signed receipt carries the token's nullifier and no payer, and the token is spent only if the call is served. A token pays for at most its value, so a request whose worst case costs more is refused with 402 token_value_too_low; council mode and verify are refused with 400 blind_unsupported. A refused, unknown, expired or already spent token is a 401 that carries WWW-Authenticate: PrivateToken challenge=\"...\". Disclosure ceilings and lanes apply to token calls exactly as to key calls. Lane unlinkable, where the router enables Oblivious HTTP, is served only for a request that arrives through the gateway (POST /api/v1/ohttp/gateway) by way of an independent relay, paid with a blind token and never a key, and only by attested providers; where the router serves the lane over Tor (data.lanes.unlinkable.via in GET /api/v1/status includes onion), a request that arrives through its onion service (data.onion.url) and is paid with a blind token qualifies in the same way, streamed or not, and a clearnet request cannot claim to have come that way; otherwise it is refused with 403 lane_requires_anonymous_auth for an API key or a wallet (unless provider.lane_downgrade is attested, which serves it on lane attested instead), 403 unlinkable_requires_relay or unlinkable_requires_independent_relay, 401 unlinkable_requires_token with the token challenge when no token is presented, or 503 no_attested_endpoint when no attested endpoint can serve the model. A request that arrives through an independent relay, is paid with a blind token and names no lane is served on lane unlinkable. On lanes attested and unlinkable the router never falls back to an endpoint without a fresh, verified attestation: it answers 503 no_attested_endpoint instead. Within a lane endpoints are weighted uptime x quality x attested_bonus / price^2 (attested_bonus 1.25 on public, 1 elsewhere). On attested and unlinkable the router still terminates TLS and sees the prompt; end-to-end encryption through the router is planned. Through the gateway, streaming needs chunked Oblivious HTTP (message/ohttp-chunked-req), where the router enables it; stream true in a message/ohttp-req is refused with 400 stream_unsupported.", "security": [ { "BearerAuth": [] }, { "WalletAuth": [] }, { "PrivateToken": [] }, {} ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "D145: opt-in API-key retry protection, scoped to account + API key + retry key for 24 hours from the first request. Canonical body and endpoint must match. Reply encrypted at rest. Headerless behavior is unchanged. See /docs/#idempotency.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]{1,128}$" } }, { "$ref": "#/components/parameters/Referer" }, { "$ref": "#/components/parameters/Title" }, { "$ref": "#/components/parameters/Payment" }, { "$ref": "#/components/parameters/PaymentSignature" }, { "$ref": "#/components/parameters/PaymentRecovery" }, { "$ref": "#/components/parameters/PayWith" }, { "$ref": "#/components/parameters/DisclosureMax" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/LaneDowngrade" }, { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/DecisionTag" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } }, "responses": { "422": { "description": "Idempotency-Key already used with a different canonical body or endpoint (idempotency_key_reused)." }, "200": { "description": "Completion JSON, or SSE events followed by data: [DONE] when stream is true.", "headers": { "Idempotent-Replay": { "description": "true when the original kept result is returned, without another charge or receipt.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Anyroute-Route": { "$ref": "#/components/headers/RouteExplanation" }, "X-Anyroute-Json-Check": { "description": "V83: valid or invalid for JSON responses; pending for streams, or pending; repair-unsupported when repair was requested. Final stream validation is in receipt.structured_output, not a changed header.", "schema": { "type": "string", "enum": [ "valid", "invalid", "pending", "pending; repair-unsupported" ] } }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" }, "X-PAYMENT-RESPONSE": { "description": "Present when an x402 payment was settled for this call: base64 JSON {success, transaction, network, payer}.", "schema": { "type": "string" } }, "PAYMENT-RESPONSE": { "description": "x402 v2: the same settlement as X-PAYMENT-RESPONSE, with the same value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "council": { "$ref": "#/components/schemas/CouncilResult" }, "verification": { "$ref": "#/components/schemas/VerificationResult" } } } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE data events; event data carries JSON chunks." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/DisclosureUnavailable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/LaneNotAvailable" }, "503": { "$ref": "#/components/responses/DisclosureProviderDown" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/embeddings": { "post": { "tags": [ "Embeddings" ], "operationId": "createEmbeddings", "summary": "Create embeddings", "description": "Uses a prepaid API key, or no key with the per-call payment flow (HTTP 402, including x402 when enabled). Input may be a string or a non-empty array with at most 2048 items. Where the router enables blind tokens, Authorization: PrivateToken token= pays with one token, exactly as for chat completions.", "security": [ { "BearerAuth": [] }, { "PrivateToken": [] }, {} ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "D145: opt-in API-key retry protection, scoped to account + API key + retry key for 24 hours from the first request. Canonical body and endpoint must match. Reply encrypted at rest. Headerless behavior is unchanged. See /docs/#idempotency.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]{1,128}$" } }, { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/Payment" }, { "$ref": "#/components/parameters/PaymentSignature" }, { "$ref": "#/components/parameters/PaymentRecovery" }, { "$ref": "#/components/parameters/DisclosureMax" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/LaneDowngrade" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" } } } }, "responses": { "422": { "description": "Idempotency-Key already used with a different canonical body or endpoint (idempotency_key_reused)." }, "200": { "description": "Embedding response with usage and signed receipt.", "headers": { "Idempotent-Replay": { "description": "true when the original kept result is returned, without another charge or receipt.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Anyroute-Route": { "$ref": "#/components/headers/RouteExplanation" }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "receipt" ], "properties": { "data": { "type": "array", "items": { "type": "object" } }, "receipt": { "$ref": "#/components/schemas/Receipt" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/DisclosureUnavailable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/LaneNotAvailable" }, "503": { "$ref": "#/components/responses/DisclosureProviderDown" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/keys": { "post": { "tags": [ "Keys" ], "operationId": "createKey", "summary": "Create a root key or authenticated sub-key", "description": "Without Authorization, creates an independent root key with an empty balance. With an authorized management or admin key, creates a virtual sub-key under that account. The response includes the new secret once; store it securely. Root-key creation does not fund the key. Never send a secret in a query string.", "security": [ { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyCreateRequest" } } } }, "responses": { "201": { "description": "New key metadata and one-time key secret.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "key", "deposit" ], "properties": { "data": { "$ref": "#/components/schemas/Key" }, "key": { "type": "string", "readOnly": true, "description": "Secret returned only on creation." }, "deposit": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } }, "get": { "tags": [ "Keys" ], "operationId": "listKeys", "summary": "List keys for the authenticated account", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Key metadata for the authenticated account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/generations": { "get": { "tags": [ "Generations" ], "operationId": "listGenerations", "summary": "List generation summaries", "description": "Returns summaries for the authenticated account. The response's next value can be passed as before to request an older page.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "Opaque cursor returned in next. Pass it through without parsing; current versions may return a legacy ISO-8601 timestamp.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Generation summaries and the next page cursor, if any.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GenerationSummary" } }, "next": { "type": [ "string", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/generation": { "get": { "tags": [ "Generations" ], "operationId": "getGeneration", "summary": "Read one generation record", "description": "Returns a full record only to the account owner, the authenticated paying wallet, or (for a call paid with a blind token, which has no account) whoever presents that spent token in Authorization: PrivateToken. The id is supplied as a query parameter because that is the implemented route; do not put API keys or other credentials in URLs.", "security": [ { "BearerAuth": [] }, { "WalletAuth": [] }, { "PrivateToken": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Generation record and receipt details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/Receipt" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/data": { "get": { "tags": [ "Data tools" ], "operationId": "listDataTools", "summary": "List the data tools", "description": "Free. The paid tools, the price per call, the Stock Token symbols with a feed, the IPX classes, and which payment methods this router accepts. Requires DATA_TOOLS_ENABLED.", "responses": { "200": { "description": "The data tools on this router.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DataToolsIndex" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/data/stock/{symbol}": { "get": { "tags": [ "Data tools" ], "operationId": "getStockTokenPrice", "summary": "Stock Token price", "description": "The USD price of one whole Stock Token from its Chainlink feed on Robinhood Chain. The feed already includes the token's ERC-8056 uiMultiplier, so the multiplier is reported but never applied again. A feed older than ESCROW_MAX_PRICE_AGE_S (302,400 s by default), dated more than five minutes ahead, unreadable or non-positive, or a token reporting paused() or oraclePaused(), is refused with 503 before any payment. With a key the price is debited from its balance (an agent rulebook sees the tool data_tool); without one the router answers 402 with its per-call offer (x402 exact once X402_PAY_TO is set).", "security": [ { "BearerAuth": [] }, {} ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9.]{1,16}$" }, "description": "Stock Token symbol, for example NVDA. GET /api/v1/data lists the symbols with a feed." }, { "$ref": "#/components/parameters/Payment" } ], "responses": { "200": { "description": "The data and what the call was charged. The payment response header carries the settlement of an x402 payment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "charge" ], "properties": { "data": { "$ref": "#/components/schemas/DataStockPrice" }, "charge": { "$ref": "#/components/schemas/DataToolCharge" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Refused before any payment and not charged: feed_stale, feed_unreadable, feed_invalid, token_paused, multiplier_unreadable or ipx_no_price. Retry-After is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/data/stock/{symbol}/actions": { "get": { "tags": [ "Data tools" ], "operationId": "getStockTokenActions", "summary": "Stock Token corporate-action status", "description": "The token's uiMultiplier (shares per raw unit, ERC-8056), the scheduled multiplier with its effective time (pending_change while it is not yet in effect), and its paused and oraclePaused views. Paid like the price.", "security": [ { "BearerAuth": [] }, {} ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9.]{1,16}$" }, "description": "Stock Token symbol, for example NVDA. GET /api/v1/data lists the symbols with a feed." }, { "$ref": "#/components/parameters/Payment" } ], "responses": { "200": { "description": "The data and what the call was charged. The payment response header carries the settlement of an x402 payment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "charge" ], "properties": { "data": { "$ref": "#/components/schemas/DataStockActions" }, "charge": { "$ref": "#/components/schemas/DataToolCharge" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Refused before any payment and not charged: feed_stale, feed_unreadable, feed_invalid, token_paused, multiplier_unreadable or ipx_no_price. Retry-After is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/data/ipx/{class}": { "get": { "tags": [ "Data tools" ], "operationId": "getDataIpx", "summary": "Inference price index (paid)", "description": "The inference price index snapshot for a model class, as GET /api/v1/ipx/{class} computes it, sold per call. Requires IPX_ENABLED; a class with no fills in its window is refused with 503 ipx_no_price before any payment.", "security": [ { "BearerAuth": [] }, {} ], "parameters": [ { "name": "class", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Index class id, for example IPX-OPEN-70B (case-insensitive)." }, { "$ref": "#/components/parameters/Payment" } ], "responses": { "200": { "description": "The data and what the call was charged. The payment response header carries the settlement of an x402 payment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "charge" ], "properties": { "data": { "$ref": "#/components/schemas/DataIpx" }, "charge": { "$ref": "#/components/schemas/DataToolCharge" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Refused before any payment and not charged: feed_stale, feed_unreadable, feed_invalid, token_paused, multiplier_unreadable or ipx_no_price. Retry-After is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/status": { "get": { "tags": [ "Status" ], "operationId": "getStatus", "summary": "Read public router configuration", "description": "Returns published runtime configuration, chain public fields, job state and catalog counts, and, where the router runs a Tor onion service, its address as data.onion.address (null otherwise). data.lanes reports each privacy lane (public, attested, unlinkable) with available, models and endpoints (how many can serve it right now) and the attested_bonus its selection weight uses; data.lanes.unlinkable.via lists the transports that carry that lane here: ohttp (an independent Oblivious HTTP relay), onion (Tor, through the onion service), both, or none when it is not available. data.per_call.x402 reports whether x402 is configured, the network names a payment may carry (versions 1 and 2), the headers the router reads and writes, and recovery: whether PAYMENT-RECOVERY is available, the message the payer signs and how long answers are kept (ttl_s). data.identity reports AGENT_IDENTITY_ENABLED (enabled), PAID_FEEDBACK_ENABLED (paid_feedback), the registration mode, the ERC-8004 registry addresses (canonical true when they are the canonical Robinhood Chain deployments), the validator, the receipt kinds that can back feedback, the half-life and the liveness interval. data.data_tools reports whether the market-data tools are on (enabled, price_usd, tools, symbols, payment) and data.decision_tags whether X-Anyroute-Decision-Tag is recorded in receipts. It is not an uptime guarantee. data.agreements reports whether agent agreements are on (enabled), the escrow and oracle contracts, start_block and finality, and rulings: enabled is true while the isolated agreement-jury worker's heartbeat (written each pass after its signer keys match the oracle's jury on chain) is younger than max_age_ms, with last_seen, threshold and jury_size; source names that heartbeat.", "responses": { "200": { "description": "Current public status snapshot.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/health": { "get": { "tags": [ "Status" ], "operationId": "getHealth", "summary": "Check process response", "description": "Returns { ok: true } when this process responds. It does not establish dependency health or uptime.", "responses": { "200": { "description": "Process responded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "const": true } } } } } } } } }, "/api/v1/receipts/verify": { "post": { "tags": [ "Receipts" ], "operationId": "verifyReceipt", "summary": "Verify a signed receipt", "description": "A v1 receipt (payload, sig, key_id) is checked as before. A v2 receipt is sent as cose (the COSE_Sign1 bytes, base64) and is checked in order: signature, then request_sha256 and response_sha256 when given, then the chunk hash chain when chunks (the data of every streamed event before the receipt, in order) are given, then the anchor path. The result reports each step (signature_valid, hashes_valid, chain_valid, inclusion_valid; null when not run) and valid is false when any step that ran failed. Either form also reports decision_tag, the X-Anyroute-Decision-Tag the receipt carries (null when none), and, when the request includes decision_tag (the SHA-256 of your order), decision_tag_valid; a mismatch makes valid false. Decision tags are recorded only while DECISION_TAGS_ENABLED is on.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReceiptVerificationRequest" }, { "$ref": "#/components/schemas/ReceiptV2VerificationRequest" } ] } } } }, "responses": { "200": { "description": "Receipt verification result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/receipts/{id}": { "get": { "tags": [ "Receipts" ], "operationId": "getReceipt", "summary": "Read a public receipt proof", "description": "Returns the v1 fields unchanged and, when the receipt has one, its v2 encoding in v2 (version is then 2). With format=cose the COSE_Sign1 bytes themselves are returned (application/cose), or as base64 text with encoding=base64; 404 when the receipt has no v2 encoding. The response also carries privacy, the plain-English privacy label computed from the payload (see GET /api/v1/receipts/{id}/privacy); it is added beside the signed fields and is not signed. A make-good refund id (rf_...) returns its signed v1 refund receipt (kind refund, naming original_receipt_id) in the same shape, without v2 or anchor.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "cose" ] } }, { "name": "encoding", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "binary", "base64" ] } } ], "responses": { "200": { "description": "Signed receipt and optional anchor proof.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Receipt" } } } }, "application/cose; cose-type=\"cose-sign1\"": { "schema": { "type": "string", "contentMediaType": "application/cose" } }, "text/plain": { "schema": { "type": "string", "contentEncoding": "base64" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/receipts/{id}/proof": { "get": { "tags": [ "Receipts" ], "operationId": "getReceiptProof", "summary": "Merkle path to the hourly root", "description": "Public. Once the receipt's hour has been rooted, the OpenZeppelin MerkleProof-compatible path from the receipt's leaf (the v2 leaf when it has one; v=1 selects the v1 leaf, which sits in the same tree) to the root. Before that, rooted is false. anchored is true only when the root was posted to ReceiptAnchor on chain and confirmed; a router without a configured chain keeps the root off chain (status local) and says anchored false.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "v", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1", "2" ] } } ], "responses": { "200": { "description": "The path, or rooted false.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReceiptProof" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/receipts/{id}/privacy": { "get": { "tags": [ "Receipts" ], "operationId": "getReceiptPrivacy", "summary": "What we saw: the privacy label for one answer", "description": "Public by id, like the receipt itself. A plain-English label computed from the receipt's signed fields: who could read the prompt, who saw the caller's network address, how the call was paid, what the router kept and what hardware answered, in five short lines (summary) and as structured fields (label). The router reads every prompt in memory to route it on every lane, and the label says so. A field the receipt does not carry is reported as not recorded, never assumed; on an unlinkable receipt the address is reported hidden only because that lane is served solely to requests that arrive over Tor (or an independent relay). The label does not verify the receipt: check its signature with POST /api/v1/receipts/verify or the client library, which also computes the same label with privacyLabel(receipt). The same object is returned as `privacy` by GET /api/v1/receipts/{id}, beside the signed payload and never inside it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The label.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PrivacyLabel" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/host-anchors/proof/{leaf}": { "get": { "tags": [ "Receipts" ], "operationId": "getHostAnchorProof", "summary": "Merkle path from an enclave receipt to its host root", "description": "Public, where the router runs with HOST_ANCHOR_ENABLED (otherwise the path does not exist). A receipt a provider's sidecar signed with its enclave key, rooted per host: the router collected it from the host's leaf feed, kept it only because its signature verified under the receipt key the host's router-verified attestation binds, and built one Merkle root per host, attestation reference and interval. anchored is true only when that root was posted with ReceiptAnchor.anchorAttested and confirmed (tx, block and anchor_index, the index in ReceiptAnchor.attestedAnchors); a root kept off chain has status local and anchored false. 404 until the leaf has been collected and rooted.", "parameters": [ { "name": "leaf", "in": "path", "required": true, "description": "The receipt's leaf, keccak256(keccak256(canonical payload || signature)), as 0x and 64 hex characters.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } ], "responses": { "200": { "description": "The host root that holds the leaf, the path to it, and its anchor status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/HostAnchorProof" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/host-anchors/proof": { "post": { "tags": [ "Receipts" ], "operationId": "postHostAnchorProof", "summary": "Merkle path for a sidecar receipt, by receipt or leaf", "description": "Public, where the router runs with HOST_ANCHOR_ENABLED (otherwise the path does not exist). A receipt a provider's sidecar signed with its enclave key, rooted per host: the router collected it from the host's leaf feed, kept it only because its signature verified under the receipt key the host's router-verified attestation binds, and built one Merkle root per host, attestation reference and interval. anchored is true only when that root was posted with ReceiptAnchor.anchorAttested and confirmed (tx, block and anchor_index, the index in ReceiptAnchor.attestedAnchors); a root kept off chain has status local and anchored false. 404 until the leaf has been collected and rooted. With receipt, the leaf is recomputed from its payload and signature, and a leaf the receipt states must match it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receipt": { "type": "object", "description": "The sidecar's receipt envelope as it was delivered.", "required": [ "payload", "sig" ], "properties": { "payload": { "type": "object" }, "sig": { "type": "string", "description": "Base64 Ed25519 signature over the canonical JSON of payload." }, "key_id": { "type": "string" }, "alg": { "type": "string", "enum": [ "Ed25519" ] }, "leaf": { "type": "string" } } }, "leaf": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "oneOf": [ { "required": [ "receipt" ] }, { "required": [ "leaf" ] } ] } } } }, "responses": { "200": { "description": "The host root that holds the leaf, the path to it, and its anchor status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/HostAnchorProof" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/.well-known/anyroute-receipt-keys.json": { "get": { "tags": [ "Receipts" ], "operationId": "getReceiptKeys", "summary": "The router's receipt signing keys", "description": "Every Ed25519 key the router has signed receipts with, current and retired, as a JWKS. A receipt is checked by canonicalizing its payload (keys sorted, no whitespace), verifying the signature with the key whose kid is the receipt's key_id, and confirming the kid is the first 16 hex characters of SHA-256 of the raw key. The same list is served at /api/v1/receipts/keys.", "responses": { "200": { "description": "The key set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptKeys" } } } }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/attestation/{providerId}": { "get": { "tags": [ "Receipts" ], "operationId": "getProviderAttestation", "summary": "What the router has verified about a provider's attestation", "description": "Public. status is attested only while the router holds a fresh attestation it verified itself, simulated only for development evidence outside production, and unverified otherwise (reason says why). checks lists what was established, each true or false; not_checked lists what this record does not cover. measurement, when present, is the last recorded image, compose and model digests with their transparency-log and on-chain state; attested_now says whether they are what the provider is attested as running now. Nothing here is the provider's own claim repeated back.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The attestation record.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProviderAttestation" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/badge/{id}.svg": { "get": { "tags": [ "Receipts" ], "operationId": "getAttestationBadge", "summary": "An attestation badge image for a provider or a model", "description": "Public, for an tag or a Markdown image. id is a provider id or a model id (author/slug). The status a prompt is served under right now: attested (a fresh attestation the router verified itself and attested retention), policy, vendor-forwarded, or unverified (unknown id, simulated evidence, or nothing current). While attested it also shows the first eight hex characters of the verified measurement (compose hash, else image digest) and of the classifier policy hash the attestation bound, and the share of the last 7 days with a fresh attestation, truncated. Only site colours, no script and no external reference. An unknown id is still an image, reading Unverified, with status 404. Nothing is checked in the viewer's browser; /badge.js does that.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A provider id, or a model id such as meta-llama/llama-3.3-70b-instruct.", "schema": { "type": "string" } }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "light", "dark" ], "default": "light" } } ], "responses": { "200": { "description": "The badge.", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } } } }, "/api/v1/attestation/summary": { "get": { "tags": [ "Receipts" ], "operationId": "getAttestationSummary", "summary": "Proof-time: how long each attesting provider has held a fresh attestation", "description": "Public. For every live or shadow provider that has a TEE and an attestation endpoint: the current status (by the same rule as GET /api/v1/attestation/{providerId}), and the share of the last 24 hours and 7 days in which the router held a fresh attestation it verified itself. A fresh attestation is one the router verified at most fresh_within_ms ago (three attestor intervals) with no failed run since; a failed run, or evidence accepted only as simulated, ends the cover at once. share is the covered part of the time the record spans (observed_ms); when the record does not reach back to the start of the window (history_complete false) the earlier time is unknown and counts neither way, and share is null when nothing is recorded. buckets divides the window into equal slices, each the percent covered, or null before the record begins. Also: measurement changes in the last 7 days, the last measurement change (which fields, from and to), the last failed check as a code with a fixed message (never the provider's own text), the pass rate of the last 7 days' checks, and the latest health-probe and canary outcomes. Nothing here is raw provider output. Returns 501 not_enabled when the router keeps no history (ATTESTATION_HISTORY_DAYS is 0).", "responses": { "200": { "description": "The summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AttestationSummary" } } } } } }, "501": { "description": "not_enabled: this router keeps no attestation history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/attestation/{providerId}/history": { "get": { "tags": [ "Receipts" ], "operationId": "getAttestationHistory", "summary": "A provider's recorded attestation, canary and probe events", "description": "Public. Newest first. Each event is one attestor run (kind attestation: ok or a failure code, the report hash, the TLS pin's SPKI hash when pinned, the verifiers that accepted the quote, the digests the run reported and whether they differ from the previous run's), one canary run (kind canary), or a change of the health probe's outcome (kind probe; only changes are recorded). Events are kept for history_days. Page with before set to the previous page's next: it encodes the moment and id of the last event, so events at the same instant are neither skipped nor repeated. Returns 404 for an unknown provider and 501 not_enabled when the router keeps no history.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "The next value of the previous page.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "attestation", "canary", "probe" ] } }, { "name": "ok", "in": "query", "required": false, "description": "Only events that passed (true) or failed (false).", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "One page of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationHistory" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "description": "not_enabled: this router keeps no attestation history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/measurements/key": { "get": { "tags": [ "Receipts" ], "operationId": "getMeasurementKey", "summary": "The key measurement bundles must be signed with", "description": "Public; 404 until the router is configured with a measurement key. A measurement bundle names the compose hash, source commit and tarball hash, model digest and image digests of a provider's attested software, with an MRTD and RTMR3 allow-list. It counts only if it is signed with this ECDSA P-256 key (SHA-256, DER signature over the bundle's canonical JSON) and the entry recording it in the transparency log verifies. key_id is the SHA-256 of the SubjectPublicKeyInfo.", "responses": { "200": { "description": "The key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "algorithm", "key_id", "public_key_pem" ], "properties": { "algorithm": { "const": "ecdsa-p256-sha256" }, "key_id": { "type": "string" }, "public_key_pem": { "type": "string" }, "public_key_spki_base64": { "type": "string" }, "transparency_log": { "type": "string", "format": "uri" }, "note": { "type": "string" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/measurements/bundles/{providerId}": { "get": { "tags": [ "Receipts" ], "operationId": "getMeasurementBundles", "summary": "A provider's signed measurement bundles and their transparency-log entries", "description": "Public; 404 until the router is configured with a measurement key. Newest first. Each item carries the bundle, its signature and digest, the status the router reached (pending, verified or rejected, with the reason), the log entry it verified (uuid, index, integration time, whether the inclusion proof, checkpoint signature and signed entry timestamp verified) and, once verified, the log's own copy of the entry (entry_record: body, inclusion proof, signed entry timestamp) so a verifier can check it without asking the log.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bundles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "status", "bundle_digest", "bundle", "signature", "transparency_log" ], "properties": { "status": { "type": "string", "enum": [ "pending", "verified", "rejected" ] }, "bundle_digest": { "type": "string" }, "compose_hash": { "type": "string" }, "signature": { "type": "string" }, "bundle": { "type": "object", "additionalProperties": true }, "transparency_log": { "type": "object", "additionalProperties": true }, "error": { "type": [ "string", "null" ] } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/mcp": { "post": { "tags": [ "MCP" ], "operationId": "mcp", "summary": "AnyRoute MCP (Streamable HTTP, stateless JSON-RPC 2.0)", "description": "One JSON-RPC 2.0 message per request: initialize, ping, tools/list and tools/call (list_models, list_attested_models, chat, verify_provider, get_receipt, verify_receipt), plus notifications, which get an empty 202. Replies are JSON, never a stream; there are no sessions. Only the chat tool needs an API key, which it spends like /api/v1/chat/completions. chat takes lane (public or attested) and disclosure (none, policy or any), meaning provider.lane and provider.disclosure: on the attested lane a prompt goes only to a provider with a fresh attestation the router verified and attested retention, and when none can answer the tool returns an error (no_attested_endpoint or disclosure_unavailable; nothing sent, nothing charged). Its result reports lane, the disclosure class the receipt records and, for an attested gateway, upstream_attestation (attested, gpu_attested, receipt_verified). list_attested_models lists the models the attested lane can serve now, with gpu_attested (true, false, or null before any verified gateway receipt). verify_provider takes provider_id and returns the router's attestation record for it in plain terms: status, TEE, verifiers, TLS pin, transparency-log status and not_checked; it is the same record as GET /api/v1/attestation/{providerId}. A connection can be made attested by default with the lane query parameter or the X-Anyroute-Lane header on the /mcp URL (disclosure and X-Anyroute-Disclosure-Max set a ceiling): the strictest setting wins, a call cannot relax it, and an unrecognised value refuses the chat call. Malformed JSON or a batch gets HTTP 400, a request carrying a foreign Origin header gets 403 and GET gets 405; all three carry a JSON-RPC error body.", "parameters": [ { "name": "lane", "in": "query", "required": false, "description": "Connection default for the chat tool: public (default) or attested. attested sends every chat prompt only to attested providers and refuses the call when none can answer. Repeat or combine with the header: the strictest applies. unlinkable is not available over MCP.", "schema": { "type": "string", "enum": [ "public", "attested" ], "default": "public" } }, { "name": "disclosure", "in": "query", "required": false, "description": "Connection default disclosure ceiling for the chat tool: none, policy or any (default). The strictest of this, the header and the call's own setting applies.", "schema": { "type": "string", "enum": [ "none", "policy", "any" ], "default": "any" } }, { "name": "X-Anyroute-Lane", "in": "header", "required": false, "description": "Same as the lane query parameter.", "schema": { "type": "string", "enum": [ "public", "attested" ], "default": "public" } }, { "name": "X-Anyroute-Disclosure-Max", "in": "header", "required": false, "description": "Same as the disclosure query parameter.", "schema": { "type": "string", "enum": [ "none", "policy", "any" ], "default": "any" } } ], "security": [ { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "A JSON-RPC 2.0 response: a result, or an error object with a JSON-RPC code.", "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "id" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "result": { "type": "object" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } } } } }, "202": { "description": "Notification accepted; the body is empty." } } } }, "/api/v1/routes": { "get": { "tags": [ "Saved Routes" ], "operationId": "listRoutes", "summary": "List the account's saved routes", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Saved routes, sorted by slug.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedRoute" } }, "limit": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Saved Routes" ], "operationId": "createRoute", "summary": "Save a routing policy callable as model @route/", "description": "Owner or admin. No prompt text is stored.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedRouteInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SavedRoute" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "route_exists, route_limit_reached (100 per account), or route_lane_unavailable: the route pins the attested lane or a disclosure ceiling and a model in its list has no provider that meets it right now (metadata.unavailable_models names them; nothing is saved).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/routes/{slug}": { "get": { "tags": [ "Saved Routes" ], "operationId": "getRoute", "summary": "Get a saved route", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The route.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SavedRoute" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "tags": [ "Saved Routes" ], "operationId": "updateRoute", "summary": "Update or rename a saved route", "description": "Each config section sent replaces that section; null clears it.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedRouteInput" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SavedRoute" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "route_exists, or route_lane_unavailable (see createRoute).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Saved Routes" ], "operationId": "deleteRoute", "summary": "Delete a saved route", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/presets": { "get": { "tags": [ "Presets" ], "operationId": "listPresets", "summary": "List the account's presets at their latest version", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Presets, sorted by name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Preset" } }, "limit": { "type": "integer" }, "limits": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/presets/{name}": { "get": { "tags": [ "Presets" ], "operationId": "getPreset", "summary": "Get a preset (the latest version, or ?version=)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A version number (3 or v3) or a hash prefix of at least 7 hex characters." } ], "responses": { "200": { "description": "The preset version.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Preset" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Presets" ], "operationId": "putPreset", "summary": "Create a preset or save a new version", "description": "Owner or admin. The body is the whole document. A change appends an immutable version; an unchanged document adds nothing (changed: false). Models, the lane and the size caps are checked as for a saved route.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetDocument" } } } }, "responses": { "200": { "description": "A new version, or the unchanged latest one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Preset" } } } } } }, "201": { "description": "Created as version 1.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Preset" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "preset_limit_reached (100 per account), preset_version_limit (100 versions per preset), or route_lane_unavailable (a model has no provider that meets the preset's lane or disclosure ceiling right now).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" } } ] }, "delete": { "tags": [ "Presets" ], "operationId": "deletePreset", "summary": "Delete a preset and every version of it", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" }, "deleted": { "type": "boolean" }, "versions": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" } } ] } }, "/api/v1/presets/{name}/versions": { "get": { "tags": [ "Presets" ], "operationId": "listPresetVersions", "summary": "List a preset's versions, newest first", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PresetVersion" } }, "latest": { "type": "integer" }, "limit": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" } } ] } }, "/api/v1/presets/{name}/diff": { "get": { "tags": [ "Presets" ], "operationId": "diffPresetVersions", "summary": "JSON diff between two versions of a preset", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Defaults to the version before `to`." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Defaults to the latest version." } ], "responses": { "200": { "description": "The changes from `from` to `to`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PresetDiff" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/presets/{name}/rollback": { "post": { "tags": [ "Presets" ], "operationId": "rollbackPreset", "summary": "Restore an earlier version as a new version", "description": "Owner or admin. Appends a version with the content (and hash) of the one named; nothing is rewritten or deleted.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "version" ], "properties": { "version": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string" } ], "description": "A version number or a hash prefix." } } } } } }, "responses": { "200": { "description": "The new latest version (changed: false when it was already current).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Preset" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "preset_version_limit, preset_invalid, or route_lane_unavailable: the version's models can no longer be served under its lane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" } } ] } }, "/api/v1/sessions": { "get": { "tags": [ "Agent Sessions" ], "operationId": "listSessions", "summary": "List the account's agent sessions", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200 } }, { "name": "before", "in": "query", "required": false, "description": "Opaque cursor returned in next. Pass it through without parsing; a plain ISO-8601 timestamp is also accepted.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sessions, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSession" } }, "next": { "type": [ "string", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Agent Sessions" ], "operationId": "createSession", "summary": "Create a short-lived, budget-capped session key for an agent run", "description": "Owner or admin. The secret is returned once. A session cannot exceed its creator's budget, expiry or model allowlist.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionCreate" } } } }, "responses": { "201": { "description": "Created; includes the one-time key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AgentSession" }, { "type": "object", "properties": { "key": { "type": "string", "readOnly": true } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/sessions/current": { "get": { "tags": [ "Agent Sessions" ], "operationId": "currentSession", "summary": "A session key's own remaining budget and time", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "This session.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentSession" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/sessions/{id}": { "get": { "tags": [ "Agent Sessions" ], "operationId": "getSession", "summary": "Session detail with recent call metadata (never content)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentSession" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Agent Sessions" ], "operationId": "endSession", "summary": "End a session now (idempotent)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Ended.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentSession" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/spend": { "get": { "tags": [ "Spend Watch" ], "operationId": "getSpend", "summary": "Spend totals, projection, anomaly flag, series, breakdowns and key budgets", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "day", "model", "key", "provider" ], "default": "day" } } ], "responses": { "200": { "description": "Spend report.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SpendReport" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/spend/alerts": { "get": { "tags": [ "Spend Watch" ], "operationId": "listSpendAlerts", "summary": "List alert rules and recent firings", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpendAlert" } }, "limits": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Spend Watch" ], "operationId": "createSpendAlert", "summary": "Create an alert rule (threshold, budget_pct or anomaly)", "description": "Owner or admin. Webhooks must be HTTPS to a public address and are delivered at most 3 times per firing.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendAlertInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SpendAlert" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "too_many_rules (20 per account).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/disclosure/{providerId}": { "get": { "tags": [ "Disclosure" ], "operationId": "getDisclosure", "summary": "A provider's disclosure profile and the class it is served under right now", "description": "Public. Every value is what the operator documented, with its own source and date; nothing is inferred from traffic. A provider with no recorded profile returns the conservative defaults (retention logs, jurisdiction unknown, legal hold undeclared, training use unknown, declared false). current.class is attested only when retention is declared attested and the provider's TEE attestation is fresh now; current.simulated is true when that attestation is a development report (never accepted in production).", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DisclosureProfile" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Disclosure" ], "operationId": "putDisclosure", "summary": "Replace a provider's disclosure profile (operator only)", "description": "Requires the operator token in X-Admin-Token or as a bearer token; an API key is not accepted. The profile is replaced as a whole: a claim that is left out reverts to its conservative default. A retention other than logs needs a legal_hold claim, and retention attested needs a provider with a TEE and attestation endpoint.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureInput" } } } }, "responses": { "200": { "description": "The stored profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DisclosureProfile" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "provider_not_attestable: retention attested was claimed for a provider with no TEE or attestation endpoint (or a development TEE in production).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/models/{author}/{slug}/lane": { "put": { "tags": [ "Lane" ], "operationId": "putModelLane", "summary": "Declare a model's variant, license and weights provenance (operator only)", "description": "Requires the operator token in X-Admin-Token or as a bearer token; an API key is not accepted. The record is replaced as a whole. The model need not be listed by any provider yet: classify it first. native_low_refusal and abliterated are restricted variants and need license and base_model on record. status candidate routes the model to no provider until the record is written again as servable.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelLaneInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The stored record." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/lane/candidates": { "get": { "tags": [ "Lane" ], "operationId": "listLaneCandidates", "summary": "Day-zero candidates and their latest scores (operator only)", "description": "Requires the operator token. When enabled, the router watches Hugging Face for new fine-tunes of the base models it is configured with, keeps those whose model card carries an allowed license (MIT or Apache-2.0 by default) and records why it rejected the rest. Status: discovered, rejected, evaluated, failed, approved or servable.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "discovered", "rejected", "evaluated", "failed", "approved", "servable" ] } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LaneCandidate" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/lane/candidates/{id}": { "get": { "tags": [ "Lane" ], "operationId": "getLaneCandidate", "summary": "One day-zero candidate (operator only)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LaneCandidate" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/lane/candidates/{id}/endpoint": { "put": { "tags": [ "Lane" ], "operationId": "linkLaneCandidateEndpoint", "summary": "Say which provider offer serves a candidate's weights (operator only)", "description": "The offer's model must declare the candidate's Hugging Face repository as its hugging_face_id, so an evaluation of one set of weights cannot approve a different model. From the moment a repository is a candidate, a model that declares it is routed to no provider until the candidate is servable.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string" }, "model": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LaneCandidate" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "repo_mismatch: the offer's model does not declare the candidate's repository. candidate_rejected: the candidate was rejected. invalid_state: the candidate is already approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/lane/candidates/{id}/evaluate": { "post": { "tags": [ "Lane" ], "operationId": "evaluateLaneCandidate", "summary": "Run the probe sets against a candidate's endpoint (operator only)", "description": "Sends the endpoint 16 benign prompts that base models commonly over-refuse (fiction, security education, medical and legal information; none harmful or illegal), 12 capability prompts with exact checks (arithmetic, JSON format, instruction following) and the router's canary set. The scores are stored. The candidate passes when its refusal rate is at most DAYZERO_MAX_REFUSAL_RATE, its capability score at least DAYZERO_MIN_CAPABILITY, its canary accuracy at least DAYZERO_MIN_CANARY and the canary precision check does not contradict the declared quantization. An approved or servable candidate that fails loses its approval and stops being served.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LaneCandidate" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "no_endpoint: link an endpoint first. endpoint_unavailable: the linked offer or provider is not live. candidate_rejected: the candidate was rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/lane/candidates/{id}/approve": { "post": { "tags": [ "Lane" ], "operationId": "approveLaneCandidate", "summary": "Approve an evaluated candidate (operator only)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "approved_by": { "type": "string", "maxLength": 64 }, "note": { "type": "string", "maxLength": 500 }, "variant": { "type": "string", "enum": [ "abliterated", "native_low_refusal" ] } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LaneCandidate" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "invalid_state: only an evaluated candidate can be approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/lane/candidates/{id}/promote": { "post": { "tags": [ "Lane" ], "operationId": "promoteLaneCandidate", "summary": "Make an approved candidate servable (operator only)", "description": "Succeeds only if the linked provider is served under attested retention with a fresh attestation and its attestation reports the in-enclave classifier as enabled: the same test routing applies to a request. Otherwise 409 not_servable says why and nothing changes. The router repeats this for approved candidates on every day-zero run.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LaneCandidate" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "invalid_state: only an approved candidate can be promoted. not_servable: no attested provider that reports the classifier serves it now; error.metadata.candidate is the candidate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/creators/claims": { "post": { "tags": [ "Creator royalties" ], "operationId": "createCreatorClaim", "summary": "Get a challenge to claim a model's creator royalty", "description": "Public and rate limited. The model must have a Hugging Face weights source on record. Commit file_content to the file named in file, on the main branch of hugging_face_id, then call the verify endpoint before expires_at. The address is the one that will receive the royalty.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "address" ], "properties": { "model": { "type": "string" }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "hf_handle": { "type": "string", "description": "Optional: refused if it is not the owner of the weights source." } } } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CreatorClaim" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "not_claimable: the model has no Hugging Face weights source on record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/creators/claims/{id}": { "get": { "tags": [ "Creator royalties" ], "operationId": "getCreatorClaim", "summary": "Read a creator claim", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CreatorClaim" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/creators/claims/{id}/verify": { "post": { "tags": [ "Creator royalties" ], "operationId": "verifyCreatorClaim", "summary": "Check the published challenge and record the royalty recipient", "description": "Public and rate limited. The router reads the repository's owner and the claim file through the Hugging Face API. The owner must still be the handle the challenge was issued to and the file must contain the challenge on its own line. On success the address becomes the model's royalty recipient at the router's default rate (5 percent unless configured otherwise, at most 20 percent): it is registered in the royalty contract first when one is configured, then recorded, and every later call to the model includes the royalty in its price. Verifying a verified claim returns it again.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CreatorClaim" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "claim_stale: the model's weights source changed since the challenge was issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "claim_expired: the challenge is no longer valid; start a new claim.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "description": "chain_failed: the royalty contract registration failed and nothing was recorded; verify again. hf_unavailable: Hugging Face could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/blind/keys": { "get": { "tags": [ "Blind tokens" ], "operationId": "getBlindKeys", "summary": "Issuer keys, the token challenge and token prices", "description": "Public; 404 unless the router enables blind tokens. One 2048-bit RSA issuer key per denomination (1000, 10000 and 100000 token-units) per epoch (a week), published before the epoch starts. token_key_id is the SHA-256 of the key's RFC 9578 SubjectPublicKeyInfo (token_key, base64url), so a client can check the key against its id. A key issues only while its status is issuing; its tokens stay redeemable until redeem_until. Every token must carry challenge_digest, the SHA-256 of the published challenge. commitments are the per-epoch values a BlindIssuer contract records. Nothing in this response is signed: compare commitments with a value recorded independently (for example on chain) before trusting the keys.", "responses": { "200": { "description": "Keys, challenge and prices.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BlindKeys" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/blind/purchase": { "post": { "tags": [ "Blind tokens" ], "operationId": "purchaseBlindTokens", "summary": "Buy blind tokens with credits", "description": "Debits the key's credits through the ledger and returns one blind signature per blinded message, in order. The client blinds the token inputs (RFC 9474) with the key named by token_key_id, and unblinds the signatures locally; the router stores counts only, never the blinded messages, the signatures or the tokens. Sending the same request again after a lost response returns the same signatures without charging again (replayed: true). Purchases count against the key's budget and are rate limited per key, capped per request (max_batch) and per account per day. A key restricted to some models cannot buy tokens. 404 unless the router enables blind tokens.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlindPurchaseRequest" } } } }, "responses": { "200": { "description": "The blind signatures.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BlindPurchase" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The key's epoch is not open yet (epoch_not_open), has ended (epoch_closed) or was revoked (token_key_revoked), or the same purchase is still being processed (purchase_in_progress).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/ohttp/keys": { "get": { "tags": [ "Oblivious HTTP" ], "operationId": "getOhttpKeys", "summary": "Gateway key configuration (RFC 9458 section 3)", "description": "Public; 404 unless the router enables Oblivious HTTP. One key configuration in application/ohttp-keys form: key identifier, KEM (DHKEM X25519 HKDF-SHA256), public key, and the KDF and AEAD pairs offered (HKDF-SHA256 with AES-128-GCM). The key changes every epoch (a day by default) and keeps opening requests for a grace period after that. This response is not signed: check it against the signed key list (GET /api/v1/ohttp/key-list) before use. Also served at /.well-known/ohttp-gateway.", "responses": { "200": { "description": "The key configuration.", "content": { "application/ohttp-keys": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "description": "The gateway has no usable key right now (ohttp_no_key). Retry after Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/ohttp/gateway": { "post": { "tags": [ "Oblivious HTTP" ], "operationId": "ohttpGateway", "summary": "Oblivious HTTP gateway: unwrap an encapsulated request, serve it, wrap the response", "description": "Sent by a relay (or, without the privacy benefit, directly). The body is a message/ohttp-req: a binary HTTP request (RFC 9292) sealed to the gateway key. The gateway serves it on the router's own routes and answers 200 with a message/ohttp-res that carries the whole inner response, errors included, so an inner 4xx is inside the encapsulation. Reachable routes: POST chat/completions and completions (streaming only with chunked Oblivious HTTP), POST embeddings, POST blind/purchase, GET blind/keys, GET models; anything else is an inner 404 route_not_allowed. Of the request's headers only Authorization, Content-Type, Accept, X-Anyroute-Lane and X-Anyroute-Disclosure-Max are passed on. Responses are zero-padded to a multiple of 256 bytes. A relay identifies itself with Authorization: Bearer :; a request without it is treated as direct and is not served the unlinkable lane. Errors before the request could be unwrapped are plain HTTP: 415, 413, 400, 422 (unknown key identifier or a request that does not decrypt, application/problem+json), 401 (a relay credential that is not recognised) and 429. Where the router enables chunked Oblivious HTTP (draft-ietf-ohai-chunked-ohttp; GET /api/v1/relays then lists gateway.chunked), the body may instead be a message/ohttp-chunked-req, answered with a message/ohttp-chunked-res (with Incremental: ?1) that is encrypted and sent chunk by chunk as the inner response is produced, so stream true works; the last chunk is sealed as the final one, so a response that ends without it was cut off and is incomplete. A chunked response that grows past the size limit ends without its final chunk. Do not retry a failed encapsulated request automatically; a repeated ciphertext is answered with an inner 409 replayed_request.", "requestBody": { "required": true, "content": { "message/ohttp-req": { "schema": { "type": "string", "format": "binary" } }, "message/ohttp-chunked-req": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The encapsulated response: message/ohttp-res for a message/ohttp-req, message/ohttp-chunked-res for a message/ohttp-chunked-req.", "content": { "message/ohttp-res": { "schema": { "type": "string", "format": "binary" } }, "message/ohttp-chunked-res": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "The encapsulated request is larger than the gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "The content type is not message/ohttp-req (or message/ohttp-chunked-req, where the router enables chunked Oblivious HTTP).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "The key identifier is unknown, expired or revoked, the ciphersuite is not offered, or the request does not decrypt with the key it names. Fetch the key configuration again.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "https://iana.org/assignments/http-problem-types#ohttp-key" }, "title": { "type": "string" } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/ohttp/key-list": { "get": { "tags": [ "Oblivious HTTP" ], "operationId": "getOhttpKeyList", "summary": "Gateway key history, signed and hash-chained", "description": "Public; 404 unless the router enables Oblivious HTTP. Every gateway key with its configuration, acceptance window and status, the next epoch's key listed as upcoming before it is served, and the relay list. The document is signed with the router's receipt signing key (Ed25519 over the canonical JSON of data; keys at GET /api/v1/receipts/keys, also registered on chain), and each key's entry_hash chains to the one before it, so a client can pin log.head and notice a key that was removed or replaced. A key's private half is destroyed when its window ends (private_key_destroyed).", "responses": { "200": { "description": "The signed key list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OhttpKeyList" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/relays": { "get": { "tags": [ "Oblivious HTTP" ], "operationId": "listRelays", "summary": "Relays clients may use for the unlinkable lane", "description": "Public; 404 unless the router enables Oblivious HTTP. Each relay has its operator, its URL and a key_id (an identifier of the credential the relay presents to the gateway, published so it is on record; the router does not verify it beyond authenticating the relay). independent is false for a relay run by the gateway's own operator: the unlinkable lane is not served through it. Pick a relay whose operator is not the gateway operator.", "responses": { "200": { "description": "The relays.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayList" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/holder": { "get": { "tags": [ "Holders" ], "operationId": "getHolder", "summary": "$ANYR balance, tier, perks, tier ladder and free credits for the wallet behind this key", "description": "Only keys from wallet sign-in have a wallet; any other key gets the same shape with wallet null and a hint. Tiers apply only when the router sets both ANYR_TOKEN_ADDRESS and HOLDER_TIERS (enabled). The balance is read live (cached for 5 minutes); when it cannot be read, balance_error is true and no tier applies. discount_bps lowers Anyroute's own fee rates (the per-call margin and the BYOK fee), never below 0; prepaid calls carry no margin, so for them the discount is 0.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Holder status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/HolderStatus" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/spend/alerts/{id}": { "patch": { "tags": [ "Spend Watch" ], "operationId": "updateSpendAlert", "summary": "Update an alert rule (kind cannot change; webhook_url null removes it)", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendAlertInput" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SpendAlert" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Spend Watch" ], "operationId": "deleteSpendAlert", "summary": "Delete an alert rule", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/messages": { "post": { "tags": [ "Anthropic Messages" ], "operationId": "createAnthropicMessage", "summary": "Create a message (Anthropic Messages API)", "description": "The Anthropic Messages API, for the Anthropic SDKs and Claude Code (ANTHROPIC_BASE_URL set to the router). Also served at /api/v1/messages. The request is converted to a chat completion and sent through /api/v1/chat/completions inside the router, so the key, balance, limits, lane, signed receipt and response headers are those of a chat call. Authenticate with x-api-key or Authorization: Bearer. The model is a catalog id (GET /v1/models) or a name the operator mapped with ANTHROPIC_MODEL_MAP; an unmapped claude-* name is a 404 that says the router serves open models. Text, image (base64 and URL), tool_use and tool_result blocks, tools and tool_choice, stop_sequences, top_k (dropped for a provider that does not list it) and metadata.user_id (sent to the provider as user) are converted; max_tokens above the model's output limit is lowered to it. Tools hosted by Anthropic, thinking and service_tier are accepted and not acted on (named in X-Anyroute-Ignored); PDF documents, mcp_servers and container are refused with a 400. The reply's id is the receipt id, and its anyroute object carries the lane, disclosure class, provider, cost, upstream_attestation where there is one, and the signed receipt. With stream true the events are message_start, ping, content_block_start, content_block_delta (text_delta, input_json_delta), content_block_stop, message_delta (billed usage and the anyroute object) and message_stop, or an error event in place of the ending; a request the router refuses before any output is an HTTP error instead of a stream. stop_reason is end_turn, max_tokens, tool_use or refusal, and stop_sequence only when the provider names the stop string that ended the answer. Errors have Anthropic's shape with an anyroute object carrying the router's own error type.", "parameters": [ { "$ref": "#/components/parameters/ProjectTag" }, { "name": "X-Anyroute-Lane", "in": "header", "required": false, "description": "public (default) or attested. attested sends the prompt only to a provider with a fresh TEE attestation the router verified and attested retention; when none can serve the model the call is refused with 409 (503 while they are down) and nothing is sent or charged. Same meaning as provider.lane; the stricter of the two applies. An unrecognised value is a 400.", "schema": { "type": "string", "enum": [ "public", "attested" ], "default": "public" } }, { "name": "X-Anyroute-Disclosure-Max", "in": "header", "required": false, "description": "Strictest ceiling on who may see the prompt: none, policy or any (default). Same meaning as provider.disclosure.", "schema": { "type": "string", "enum": [ "none", "policy", "any" ], "default": "any" } }, { "name": "anthropic-version", "in": "header", "required": false, "description": "Accepted and ignored.", "schema": { "type": "string" } }, { "name": "anthropic-beta", "in": "header", "required": false, "description": "Accepted and ignored.", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] }, { "AnthropicApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequest" } } } }, "responses": { "200": { "description": "The message, or Anthropic server-sent events when stream is true.", "headers": { "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "Request-Id": { "description": "An id for this request (req_...), also in the error body's request_id.", "schema": { "type": "string" } }, "X-Anyroute-Ignored": { "description": "Present when the request asked for something that is accepted and not acted on: thinking, service_tier, or tools hosted by Anthropic (tool:). A comma separated list.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessage" } }, "text/event-stream": { "schema": { "type": "string", "description": "Anthropic SSE: each event has an event: line naming its type and a data: JSON object." } } } }, "default": { "$ref": "#/components/responses/AnthropicError" } } } }, "/v1/messages/count_tokens": { "post": { "tags": [ "Anthropic Messages" ], "operationId": "countAnthropicMessageTokens", "summary": "Count the tokens of a message (estimate)", "description": "The body of POST /v1/messages without max_tokens. Returns the router's own estimate of the prompt: about one token for every three characters of text and JSON, plus 1,600 for each image. It is not a tokenizer's count, it costs nothing, and it needs a key. The model is not looked up. Also served at /api/v1/messages/count_tokens.", "security": [ { "BearerAuth": [] }, { "AnthropicApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicCountTokensRequest" } } } }, "responses": { "200": { "description": "The estimate.", "headers": { "Request-Id": { "description": "An id for this request (req_...), also in the error body's request_id.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "input_tokens" ], "properties": { "input_tokens": { "type": "integer", "minimum": 0 } } } } } }, "default": { "$ref": "#/components/responses/AnthropicError" } } } }, "/api/v1/responses": { "post": { "tags": [ "Responses" ], "operationId": "createResponse", "summary": "Create a response (OpenAI Responses API)", "description": "The OpenAI Responses API, for the OpenAI Agents SDK, the Codex CLI and other Responses clients (POST /v1/responses is the same route). It is an adapter over POST /api/v1/chat/completions: the request is translated and sent to that route in-process with the same credentials and headers, so keys, wallet and per-call payment, blind tokens, limits, disclosure ceilings, lanes, signed receipts and error responses are the chat route's own, and the answer is returned in the Responses shape. With stream true the body is the Responses event stream, each frame an event: line and a data: line carrying type and sequence_number: response.created, response.in_progress, response.output_item.added, response.content_part.added, response.output_text.delta, response.output_text.done, response.content_part.done, response.function_call_arguments.delta, response.function_call_arguments.done, response.custom_tool_call_input.delta and .done, response.output_item.done and last response.completed (or response.incomplete when the answer was cut off by max_output_tokens). A failure after the stream has started is an error event followed by response.failed; there is no [DONE]. Stateless by design: nothing is stored, so store must be false (the default; true is refused), and previous_response_id, conversation, background, stored prompts and file or item references are refused with a 400 whose error.param names the field. Send the whole conversation in input on every request, including function_call and function_call_output items for tool round trips. GET, DELETE and cancel under /api/v1/responses/{id} answer 404. Function tools and custom (freeform) tools run. A custom tool, such as Codex's apply_patch, is offered to the model as a function with one string argument, input; its description, a line saying it takes freeform text and its grammar, if it has one, become the function's description, as guidance only: no grammar is enforced. A call to it comes back as a custom_tool_call item with the text as input (streamed as response.custom_tool_call_input.delta, then response.custom_tool_call_input.done), and a custom_tool_call_output input item is its result on the next turn. Hosted tools (web_search, file_search, code_interpreter, computer_use, image_generation, mcp) are refused with a 400 naming the tool, because AnyRoute hosts none; run the work in your own code and return it as a function_call_output or custom_tool_call_output. Route with provider (lane, disclosure and the router's other preferences) or the X-Anyroute-Lane header; the stricter of the two applies, and a request no provider can serve under the lane is refused (409 lane_unavailable) with nothing sent and nothing charged. The response carries X-Receipt-Id, Inference-Id and X-Anyroute-Lane (and X-Anyroute-Policy-Hash where the serving endpoint attested one), and its metadata carries anyroute_receipt_id, anyroute_lane and, once known, anyroute_disclosure. Other Responses options (include, truncation, service_tier, prompt_cache_key, safety_identifier, stream_options) are accepted and ignored.", "security": [ { "BearerAuth": [] }, { "WalletAuth": [] }, { "PrivateToken": [] }, {} ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "D145: opt-in API-key retry protection, scoped to account + API key + retry key for 24 hours from the first request. Canonical body and endpoint must match. Reply encrypted at rest. Headerless behavior is unchanged. See /docs/#idempotency.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]{1,128}$" } }, { "$ref": "#/components/parameters/Referer" }, { "$ref": "#/components/parameters/Title" }, { "$ref": "#/components/parameters/Payment" }, { "$ref": "#/components/parameters/PaymentSignature" }, { "$ref": "#/components/parameters/PaymentRecovery" }, { "$ref": "#/components/parameters/PayWith" }, { "$ref": "#/components/parameters/DisclosureMax" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/LaneDowngrade" }, { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/DecisionTag" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" } } } }, "responses": { "422": { "description": "Idempotency-Key already used with a different canonical body or endpoint (idempotency_key_reused)." }, "200": { "description": "A Response object, or the Responses event stream when stream is true.", "headers": { "Idempotent-Replay": { "description": "true when the original kept result is returned, without another charge or receipt.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" }, "X-PAYMENT-RESPONSE": { "description": "Present when an x402 payment was settled for this call: base64 JSON {success, transaction, network, payer}.", "schema": { "type": "string" } }, "PAYMENT-RESPONSE": { "description": "x402 v2: the same settlement as X-PAYMENT-RESPONSE, with the same value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesObject" } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE frames (event: and data: lines) in the order described above; the response.completed, response.incomplete and response.failed frames carry the whole Response object." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/DisclosureUnavailable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/LaneNotAvailable" }, "503": { "$ref": "#/components/responses/DisclosureProviderDown" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/responses/{id}": { "get": { "tags": [ "Responses" ], "operationId": "getResponse", "summary": "Not available: responses are not stored", "description": "Always 404 (responses_not_stored), like DELETE and POST .../cancel and GET .../input_items on this path. AnyRoute is stateless: it stores no responses, conversations or input items, so there is nothing to retrieve. A response is returned by the call that creates it. The call's signed receipt, which holds no prompt or answer, is at GET /api/v1/receipts/{id}: the id is in the X-Receipt-Id header and the response's metadata.anyroute_receipt_id.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/rag": { "post": { "tags": [ "Private RAG" ], "operationId": "createRagAnswer", "summary": "Answer a question from documents you send, keeping nothing", "description": "Retrieval-augmented answers over documents sent with the question, with nothing kept. The router cuts the documents into overlapping chunks, embeds the chunks and the question through POST /api/v1/embeddings (in batches), ranks the chunks by cosine similarity in memory, and answers from the best top_k through POST /api/v1/chat/completions, citing numbered sources. Every call is an ordinary call of your key: billed, limited, routed by lane and receipted, and the response lists every receipt id with its lane, the disclosure class it was served under and, for an attested gateway, its upstream_attestation check. Needs a prepaid API key (Authorization: Bearer); per-call payment and blind tokens are not accepted. Lane: send provider.lane (public or attested) or provider.disclosure (none, policy, any), or the X-Anyroute-Lane and X-Anyroute-Disclosure-Max headers, and every call is held to exactly that and refused, never downgraded: on the attested lane 503 no_attested_endpoint (error.metadata.reason none_attested, or attested_endpoints_down with Retry-After); with only a disclosure ceiling 409 disclosure_unavailable, or 503 disclosure_provider_unavailable while qualifying providers are down; or 502 upstream_not_attested when an attested gateway's receipt does not show an attested upstream (the reply is withheld and the call is billed). A lane or ceiling pinned on the key (routing.provider) applies to every step, not only the chat call. A model the router resolves itself (a saved route, an alias of the key, anyroute/...) can pin a lane of its own, so a request naming one must state provider.lane (400 lane_required). Send none and the attested lane is used when the chat model and the embedding model both have an attested endpoint; otherwise the public lane is used and lane_note says why. embedding_model defaults to qwen/qwen3-embedding-8b, else the cheapest embedding model, preferring models with an attested endpoint. Unlinkable is not available. An error from a step is that step's own status and error.type, with error.metadata.step (embeddings or chat) and error.metadata.receipts, the calls already made and billed. Caps (configurable): 200 documents, 2 MiB of document text, 2000 chunks and 64 embeddings calls per request, 413 payload_too_large above them. With stream true the embeddings run first (a refusal there, or at the start of the chat call, is an ordinary JSON error); the stream then sends a chat.completion.chunk event with choices [] and rag.object rag.sources (the sources and the embeddings receipts), the chat stream exactly as /api/v1/chat/completions sends it, an event with rag.object rag.summary (all receipts, totals and, if the chat call was refused mid-stream, error), and data: [DONE]. Nothing of the documents, the question or the answer is stored. The documents, their chunks and vectors and the question live in the memory of the one request that carries them and are dropped when it ends; this endpoint writes them to no database, cache or file, does not log them and never uses the response cache. What remains is what any call leaves: each embeddings call and the chat call is a generation of the key, with a signed receipt holding ids, model, provider, lane, token counts, cost, timing and the SHA-256 of the request and of the response, not their text (a hash confirms an exact guess; it does not reveal text). The text does leave the router: the chunks and the question go to the embedding model's provider and the question and the best chunks go to the chat model's provider. What those providers see and keep depends on the lane; on the attested lane only providers with attested retention and a fresh attestation the router verified are used, which shows what code is running, not what it does with the text.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/PayWith" }, { "$ref": "#/components/parameters/DisclosureMax" }, { "$ref": "#/components/parameters/Lane" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RagRequest" } } } }, "responses": { "200": { "description": "The answer, its sources and the receipt of every call; or, with stream true, Server-Sent Events: a chat.completion.chunk with choices [] and rag.object rag.sources, the chat stream, a chunk with rag.object rag.summary, then data: [DONE]. The headers are those of the chat call, except X-Anyroute-Disclosure, which is the weakest class among all the calls (and is left out when a call's class is not known), and X-Anyroute-Policy-Hash, which is sent only when every call reported the same one.", "headers": { "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RagAnswer" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events; each data: line is a JSON object of the chat.completion.chunk shape." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "No provider meets provider.disclosure for a step (disclosure_unavailable), or no embedding model does. Nothing was sent to a provider for that step. error.metadata.step names it and error.metadata.receipts lists the calls already made.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "More documents, bytes of document text, chunks or embeddings calls than the router allows in one request (payload_too_large). error.metadata.limit is the cap. Nothing was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "description": "A step failed after the router accepted the request: upstream_not_attested (an attested gateway's receipt did not show an attested upstream; the reply was withheld and the call is billed), providers_unavailable, or invalid_embedding_response. error.metadata.step and error.metadata.receipts say where it stopped and what was billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "$ref": "#/components/responses/DisclosureProviderDown" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/tlog/checkpoint": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogCheckpoint", "summary": "Newest checkpoint, with the cosignatures collected so far", "description": "Public; 404 unless the router enables the transparency log. A C2SP signed note: the checkpoint text (origin, tree size, base64 root hash; no extension lines), a blank line, the log's Ed25519 signature line, then one cosignature/v1 line per configured witness that has cosigned this tree size. Verify the log's line against the log key pinned out of band (GET /api/v1/tlog shows it, but a client must not take it from the log it is checking), and count witness lines against the witness keys you trust. Served with Cache-Control: no-cache.", "responses": { "200": { "description": "The checkpoint note.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "router.example/tlog\n12\nq0qBmQ4H0cMA5Tq3kQ0V8wQv1c5V3bI1n4r7FQ0y2Hc=\n\n— router.example/tlog \n— witness.example/w1 \n" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/tlog/tile/{level}/{index}": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogTile", "summary": "Merkle tree tile (tlog-tiles, height 8)", "description": "Public; 404 unless the router enables the transparency log, and for any tile or width the tree does not have yet. The concatenated 32-byte node hashes of tree level 8 x level, indices 256 x N to 256 x N + W. The index path is the tlog-tiles encoding of N (groups of three digits, all but the last prefixed with x: 1234067 is x001/x234/067) and may end in .p/ for a partial tile of width 1 to 255. A tile of a given width never changes, so tiles are served with Cache-Control: public, max-age=31536000, immutable.", "parameters": [ { "name": "level", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 63 } }, { "name": "index", "in": "path", "required": true, "description": "The encoded tile index, optionally followed by .p/; it may contain slashes.", "schema": { "type": "string", "example": "x001/234.p/17" } } ], "responses": { "200": { "description": "The tile.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/tlog/tile/entries/{index}": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogEntryBundle", "summary": "Entry bundle (tlog-tiles)", "description": "Public; 404 unless the router enables the transparency log. The entries at leaf indices 256 x N to 256 x N + W, each as a big-endian 16-bit length followed by the entry: the canonical JSON {v, type: \"anyroute.tlog.entry\", kind, sha256, key}, whose leaf hash is SHA-256(0x00 || entry). Same index encoding and caching as the hash tiles.", "parameters": [ { "name": "index", "in": "path", "required": true, "description": "The encoded tile index, optionally followed by .p/; it may contain slashes.", "schema": { "type": "string", "example": "000.p/12" } } ], "responses": { "200": { "description": "The entry bundle.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogInfo", "summary": "The log: origin, verifier key, witnesses, quorum and newest checkpoint", "description": "Public; 404 unless the router enables the transparency log. What entry kinds exist and which witnesses the router collects cosignatures from. Pin the log's verifier key and the witness keys from a source other than the log itself. With Rekor anchoring on (TLOG_REKOR_ENABLED), rekor names the anchoring key and the newest anchored checkpoint's Rekor entry; it is null otherwise.", "responses": { "200": { "description": "The log description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlogInfo" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/witnessed": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogWitnessedCheckpoint", "summary": "Newest checkpoint cosigned by the witness quorum", "description": "Public; 404 (not_witnessed) until some checkpoint carries cosignatures from at least TLOG_WITNESS_QUORUM configured witnesses. Same note format as /tlog/checkpoint.", "responses": { "200": { "description": "The checkpoint note.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "router.example/tlog\n12\nq0qBmQ4H0cMA5Tq3kQ0V8wQv1c5V3bI1n4r7FQ0y2Hc=\n\n— router.example/tlog \n— witness.example/w1 \n" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/checkpoints/{size}": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogCheckpointBySize", "summary": "One checkpoint with its cosignatures", "parameters": [ { "name": "size", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "description": "Public; 404 (unknown_checkpoint) when the log never signed a checkpoint of that tree size.", "responses": { "200": { "description": "The checkpoint note.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "router.example/tlog\n12\nq0qBmQ4H0cMA5Tq3kQ0V8wQv1c5V3bI1n4r7FQ0y2Hc=\n\n— router.example/tlog \n— witness.example/w1 \n" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/lookup": { "get": { "tags": [ "Transparency log" ], "operationId": "lookupTlogEntry", "summary": "The entry for a key or configuration", "description": "Public; 404 (not_logged) when the key is not in the log. sha256 is the digest a client computes from what it holds: the raw Ed25519 receipt key, the encoded Oblivious HTTP key configuration, the blind issuer SubjectPublicKeyInfo (its token_key_id), the canonical measurement bundle, or the canonical JSON of a sidecar's bindings.", "parameters": [ { "$ref": "#/components/parameters/TlogKind" }, { "$ref": "#/components/parameters/TlogSha256" } ], "responses": { "200": { "description": "The entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlogEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/proof": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogProof", "summary": "An entry with its inclusion proof and, on request, a consistency proof", "description": "Public. The entry for (kind, sha256), a checkpoint that includes it (by default the newest one the witness quorum cosigned, else, with Rekor anchoring on, the newest anchored one, else the newest one), the RFC 6962 inclusion proof to that checkpoint's root and, with from, the consistency proof between tree size from and the checkpoint's size. Nothing here is trusted by itself: a client checks the log signature and witness cosignatures (or, with anchoring, the checkpoint's Rekor entry in checkpoint.rekor) on the checkpoint, recomputes the leaf from the entry and verifies both proofs. 404 not_logged, 409 not_yet_included when the requested checkpoint predates the entry.", "parameters": [ { "$ref": "#/components/parameters/TlogKind" }, { "$ref": "#/components/parameters/TlogSha256" }, { "name": "size", "in": "query", "description": "Prove against the checkpoint of this tree size instead.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "from", "in": "query", "description": "The tree size of the newest checkpoint the client already holds.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "The proof bundle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlogProof" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The chosen checkpoint does not include the entry yet (not_yet_included).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/consistency": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogConsistency", "summary": "Consistency proof between two tree sizes", "description": "Public. The RFC 6962 consistency proof from tree size from to tree size to (to at most the current size). Witnesses use it before cosigning; clients use it to check that a newer checkpoint extends one they saw.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "The proof.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlogConsistency" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/cosignatures": { "post": { "tags": [ "Transparency log" ], "operationId": "postTlogCosignature", "summary": "A witness hands in its cosignature on a checkpoint", "description": "Public, rate limited per client address (TLOG_COSIGN_RPM). The body is the checkpoint note as the log served it with the witness's cosignature/v1 line added (the C2SP tlog-cosignature format: key id, 8-byte timestamp and Ed25519 signature over \"cosignature/v1\\ntime \\n\" and the checkpoint text). Only lines from witnesses in TLOG_WITNESSES count; each valid one is kept, the newest per witness and tree size. A witness should cosign only after verifying a consistency proof from the last checkpoint it cosigned (scripts/tlog-witness.ts does). 400 invalid_checkpoint or unknown_log, 403 unknown_witness or invalid_cosignature, 404 unknown_checkpoint, 409 checkpoint_mismatch when the text is not what the log signed for that size.", "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string", "maxLength": 16384 } } } }, "responses": { "200": { "description": "The cosignatures that were accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlogCosignatureResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The note is not the checkpoint the log signed for that size (checkpoint_mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The note is larger than 16 KiB (payload_too_large).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/rekor": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogRekorAnchors", "summary": "Rekor anchoring: the anchoring key, the newest anchored checkpoint and a list of anchors", "description": "Public; 404 (rekor_not_enabled) unless the router anchors its checkpoints in Rekor (TLOG_REKOR_ENABLED). Each checkpoint the log moves to is recorded, at most once per TLOG_REKOR_MIN_INTERVAL_MS, as a hashedrekord entry in the Sigstore Rekor log at rekor_url: the entry holds the SHA-256 of the checkpoint as the log signed it (the checkpoint text, a blank line and the log's own signature line, without cosignatures) and an ECDSA P-256 signature over it by the anchoring key. The router verifies the entry's inclusion proof (and, with REKOR_PUBLIC_KEY, Rekor's signed checkpoint and signed entry timestamp) before it lists it. anchors lists every verified anchor, newest checkpoint first; page with before=next_before. Anyone can compare the entries the anchoring key has in Rekor with this list: an entry the list does not explain, or two anchored checkpoints of one size with different roots, is a split view.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "required": false, "description": "Only anchors of checkpoints smaller than this tree size.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "The anchoring key and the anchors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlogRekorAnchors" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/rekor/key": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogRekorKey", "summary": "The anchoring key (ECDSA P-256)", "description": "Public; 404 (rekor_not_enabled) unless the router anchors its checkpoints in Rekor (TLOG_REKOR_ENABLED). The public key that signs the log's Rekor entries, and its key_id (SHA-256 of the SubjectPublicKeyInfo, hex). Every entry carries this key, so it can be searched for in Rekor. A client that checks anchors pins this key out of band. Served with Cache-Control: public, max-age=300.", "responses": { "200": { "description": "The anchoring key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlogRekorKey" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/tlog/rekor/{size}": { "get": { "tags": [ "Transparency log" ], "operationId": "getTlogRekorAnchorBySize", "summary": "The Rekor entry that anchors one checkpoint", "description": "Public; 404 (rekor_not_enabled) unless the router anchors its checkpoints in Rekor (TLOG_REKOR_ENABLED). 404 (not_anchored) when no verified Rekor entry anchors a checkpoint of that tree size under the current anchoring key.", "parameters": [ { "name": "size", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "The anchor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TlogRekorAnchor" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/batches": { "post": { "tags": [ "Batches" ], "operationId": "createBatch", "summary": "Create a batch of chat or embeddings requests, run in the background at a discount", "description": "Also at POST /v1/batches. The OpenAI Batch API shape without files: send the lines inline as requests (a list) or input_jsonl (JSON Lines text), one request per line with a unique custom_id (at most 64 characters), method POST, a url of /v1/chat/completions or /v1/embeddings (the /api/v1 forms are accepted too) and the request body. endpoint, when given, must match every line's url. input_file_id is refused with 400: there is no files endpoint, so send requests or input_jsonl. stream true, council mode (model anyroute/council) and verify are refused in a batch. A batch with an invalid line is not created: the 400 invalid_request carries error.metadata.errors, a list of { line, code, message } with 1-based line numbers. Needs a prepaid key. The lines run on the router's worker in spare capacity, so a batch can take minutes; lines not run within the 24h completion window expire and are not charged. Each line is billed at 50% of the normal price (BATCH_DISCOUNT_BPS 5000), a failed line is not charged, and every answered line gets its own signed receipt. Lanes, provider preferences, key budgets and key rate limits apply to each line exactly as to a normal call. Limits (operator settings): BATCH_MAX_LINES (1000 lines), BATCH_MAX_BYTES (8 MiB of input) and BATCH_MAX_ACTIVE (2 unfinished batches per key; one more is refused with 429 batch_limit); a batch over the line or byte limit is refused. The request lines and answers are never written to the database: until the results expire they are kept sealed (AES-256-GCM, with a key derived from the router's secret) in Redis, or in the router's memory without Redis, and then deleted. The database keeps only counts, costs, statuses and generation ids.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } } }, "responses": { "200": { "description": "The batch was accepted; its status is validating until the worker picks it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } }, "get": { "tags": [ "Batches" ], "operationId": "listBatches", "summary": "List the key's batches, newest first", "description": "Also at GET /v1/batches. Pages with limit and after (the id of the last batch of the previous page).", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Batches per page.", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "after", "in": "query", "required": false, "description": "A batch id: list the batches after it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of batches, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/batches/{id}": { "get": { "tags": [ "Batches" ], "operationId": "getBatch", "summary": "Read a batch: status, counts and cost", "description": "Also at GET /v1/batches/{id}. Poll it until status is completed, failed, expired or cancelled, then read the output and errors files.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id (batch_...).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/batches/{id}/cancel": { "post": { "tags": [ "Batches" ], "operationId": "cancelBatch", "summary": "Cancel a batch", "description": "Also at POST /v1/batches/{id}/cancel. The status becomes cancelling, then cancelled: lines already running finish and are billed, lines not started are never run or billed and appear in the errors file.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id (batch_...).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The batch, cancelling or cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/batches/{id}/output": { "get": { "tags": [ "Batches" ], "operationId": "getBatchOutput", "summary": "The answered lines of a batch, as JSONL", "description": "Also at GET /v1/batches/{id}/output. One line per answered request: { id: batch_req_..., custom_id, response: { status_code: 200, request_id: the generation id, body: the normal chat or embeddings response, usage.cost and receipt included }, error: null }. Kept for BATCH_RESULTS_TTL (24 hours by default) after the batch finishes.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id (batch_...).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The answered lines.", "content": { "application/jsonl": { "schema": { "type": "string", "description": "JSON Lines: one BatchResultLine object per line." }, "x-line-schema": { "$ref": "#/components/schemas/BatchResultLine" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "The results were deleted: they are kept for BATCH_RESULTS_TTL (24 hours by default) after the batch finishes (batch_results_expired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/batches/{id}/errors": { "get": { "tags": [ "Batches" ], "operationId": "getBatchErrors", "summary": "The failed and unrun lines of a batch, as JSONL", "description": "Also at GET /v1/batches/{id}/errors. One line per failed or unrun request: { id, custom_id, response: { status_code, request_id, body: { error } } or null for a line that never ran, error: { code, message } }. Failed and unrun lines are not charged. Kept for BATCH_RESULTS_TTL (24 hours by default) after the batch finishes.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id (batch_...).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The failed and unrun lines.", "content": { "application/jsonl": { "schema": { "type": "string", "description": "JSON Lines: one BatchResultLine object per line." }, "x-line-schema": { "$ref": "#/components/schemas/BatchResultLine" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "The results were deleted: they are kept for BATCH_RESULTS_TTL (24 hours by default) after the batch finishes (batch_results_expired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/ollama/api/version": { "get": { "tags": [ "Ollama" ], "operationId": "ollamaVersion", "summary": "The Ollama API version this endpoint speaks", "responses": { "200": { "description": "The version.", "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "string", "examples": [ "0.12.6" ] } } } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/ollama/api/tags": { "get": { "tags": [ "Ollama" ], "operationId": "ollamaTags", "summary": "List models in Ollama's shape", "description": "The live catalog, as GET /api/v1/models lists it. Each name is a catalog id with Ollama's :latest tag (a routing suffix such as :free or :private works as a tag too). size is 0 (there are no local weights) and digest is the SHA-256 of the catalog id. X-Anyroute-Lane: attested lists only the models that lane can serve now. Public.", "parameters": [ { "$ref": "#/components/parameters/Lane" } ], "responses": { "200": { "description": "The models.", "content": { "application/json": { "schema": { "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/OllamaModel" } } } } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/ollama/api/ps": { "get": { "tags": [ "Ollama" ], "operationId": "ollamaPs", "summary": "Models held in memory (always none)", "description": "Models are served on demand by hosted providers, so the list is always empty.", "responses": { "200": { "description": "An empty list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "maxItems": 0, "items": {} } } } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/ollama/api/show": { "post": { "tags": [ "Ollama" ], "operationId": "ollamaShow", "summary": "Describe a model", "description": "details, capabilities (completion, tools, vision, thinking, or embedding) and the context length in model_info. Public. An unknown model is a 404.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "name": { "type": "string", "description": "Older clients send the name here." } } } } } }, "responses": { "200": { "description": "The model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaShowResponse" } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/ollama/api/chat": { "post": { "tags": [ "Ollama" ], "operationId": "ollamaChat", "summary": "Chat (Ollama)", "description": "Converted to a chat completion and sent through /api/v1/chat/completions in-process, so the key, its balance and limits, the lane and the signed receipt are those of a chat call. Streams NDJSON unless stream is false: lines with done false, tool calls whole in one line, then a closing line with done true, done_reason, the counts and durations (nanoseconds) and an anyroute object with the receipt id. A request the router refuses before any output is an HTTP error; a failure after output has begun is an {\"error\"} line. No messages: the model is loaded as Ollama does (done_reason load), with no call and no charge.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/DisclosureMax" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaChatRequest" } } } }, "responses": { "200": { "description": "The reply, or its NDJSON stream.", "headers": { "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Ignored": { "description": "Present when the request asked for something that is accepted and not acted on: options that tune a local runtime (options.num_ctx and the like), suffix, template, raw or context. A comma separated list.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaChatResponse" } }, "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/OllamaChatResponse" } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/ollama/api/generate": { "post": { "tags": [ "Ollama" ], "operationId": "ollamaGenerate", "summary": "Generate (Ollama)", "description": "system and prompt are sent as a system and a user message through /api/v1/chat/completions, with the same billing, lanes and receipts. The answer is in response. Streams NDJSON unless stream is false. suffix, template, raw and context are accepted and named in X-Anyroute-Ignored.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/DisclosureMax" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaGenerateRequest" } } } }, "responses": { "200": { "description": "The reply, or its NDJSON stream.", "headers": { "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Ignored": { "description": "Present when the request asked for something that is accepted and not acted on: options that tune a local runtime (options.num_ctx and the like), suffix, template, raw or context. A comma separated list.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaGenerateResponse" } }, "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/OllamaGenerateResponse" } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/ollama/api/embed": { "post": { "tags": [ "Ollama" ], "operationId": "ollamaEmbed", "summary": "Embeddings (Ollama)", "description": "Sent through /api/v1/embeddings, with the same billing, lanes and receipts.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/DisclosureMax" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "dimensions": { "type": "integer", "minimum": 1 }, "truncate": { "type": "boolean", "description": "Accepted and ignored." }, "keep_alive": { "description": "Accepted and ignored." }, "options": { "type": "object", "description": "Accepted and named in X-Anyroute-Ignored." }, "provider": { "type": "object" } } } } } }, "responses": { "200": { "description": "The vectors, in the order of input.", "headers": { "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Ignored": { "description": "Present when the request asked for something that is accepted and not acted on: options that tune a local runtime (options.num_ctx and the like), suffix, template, raw or context. A comma separated list.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "embeddings" ], "properties": { "model": { "type": "string" }, "embeddings": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, "total_duration": { "type": "integer" }, "load_duration": { "type": "integer" }, "prompt_eval_count": { "type": "integer" } } } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/ollama/api/embeddings": { "post": { "tags": [ "Ollama" ], "operationId": "ollamaEmbeddingsLegacy", "summary": "One embedding (older Ollama endpoint)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/DisclosureMax" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string" }, "prompt": { "type": "string" } } } } } }, "responses": { "200": { "description": "The vector.", "headers": { "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Ignored": { "description": "Present when the request asked for something that is accepted and not acted on: options that tune a local runtime (options.num_ctx and the like), suffix, template, raw or context. A comma separated list.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "embedding" ], "properties": { "embedding": { "type": "array", "items": { "type": "number" } } } } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/ollama/api/pull": { "post": { "tags": [ "Ollama" ], "operationId": "ollamaPull", "summary": "Pull a model (nothing to download)", "description": "A listed model is ready as soon as it is named, so the pull succeeds at once with {\"status\":\"success\"} (one NDJSON line unless stream is false). An unknown model is a 404. create, copy, push, delete and blob uploads are 501s.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "stream": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Done.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "success" } } } }, "application/x-ndjson": { "schema": { "type": "object", "properties": { "status": { "const": "success" } } } } } }, "default": { "$ref": "#/components/responses/OllamaError" } } } }, "/api/v1/keys/current-ip": { "get": { "tags": [ "Keys" ], "operationId": "getCurrentClientIp", "summary": "Return your client IP once", "description": "E148: Requires bearer owner/admin permission. Uses the existing trusted-proxy hop helper; no address is stored or logged by this feature. Onion and unlinkable ingress is refused. Response has Cache-Control: no-store.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Client address in memory only.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ip": { "type": "string" } }, "required": [ "ip" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "description": "Client address unavailable." } } } }, "/api/v1/keys/{hash}": { "get": { "tags": [ "Keys" ], "operationId": "getKey", "summary": "Get one key, with its tracing export status", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The key's hash (Key.hash)." } ], "responses": { "200": { "description": "The key's metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Key" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } }, "patch": { "tags": [ "Keys" ], "operationId": "updateKey", "summary": "Update a key's limits, auto top-up, guardrails or tracing destination", "description": "Accepts the fields of KeyCreateRequest. `topup` sets or clears the key's auto top-up rule (KeyTopup). `tracing` sets where spans of this key's public-lane calls go: your OpenTelemetry collector (OTLP/HTTP JSON), Langfuse or Helicone. Spans follow the OpenTelemetry GenAI semantic conventions and add anyroute.cost_usd, anyroute.receipt_id, anyroute.lane and anyroute.provider. Prompt and completion text is included only with include_content: true. Attested and unlinkable lane calls are never exported.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The key's hash (Key.hash)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyCreateRequest" }, "examples": { "honeycomb": { "summary": "Honeycomb over OTLP", "value": { "tracing": { "type": "otlp", "endpoint": "https://api.honeycomb.io", "headers": { "x-honeycomb-team": "YOUR_API_KEY" } } } }, "langfuse": { "summary": "Langfuse, with content", "value": { "tracing": { "type": "langfuse", "public_key": "pk-lf-...", "secret_key": "sk-lf-...", "include_content": true } } }, "off": { "summary": "Stop exporting", "value": { "tracing": null } }, "topup": { "summary": "Auto top-up: below $2 left, add $10, at most $50 a week", "value": { "limit": 20, "topup": { "below_usd": 2, "add_usd": 10, "max_per_week_usd": 50 } } } } } } }, "responses": { "200": { "description": "The key's metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Key" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/rerank": { "post": { "tags": [ "Rerank" ], "operationId": "createRerank", "summary": "Rerank documents", "description": "Orders documents by relevance to a query through a provider's own /rerank. Served only by models whose output modalities include rerank; any other model, or a router where no provider lists a rerank model, is 404 model_not_found. Priced per token (pricing.prompt) and per search unit (pricing.request) as the provider reports them. An answer that is not a valid ranking of the documents sent is a failed attempt: the next provider is tried, and 502 providers_unavailable with nothing charged if none answers. Keys, budgets, per-call payment (HTTP 402), blind tokens, lanes, the disclosure ceiling and provider preferences work as for embeddings; the Oblivious HTTP gateway does not carry rerank calls yet. Also served at /v1/rerank.", "security": [ { "BearerAuth": [] }, { "PrivateToken": [] }, {} ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "D145: opt-in API-key retry protection, scoped to account + API key + retry key for 24 hours from the first request. Canonical body and endpoint must match. Reply encrypted at rest. Headerless behavior is unchanged. See /docs/#idempotency.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]{1,128}$" } }, { "$ref": "#/components/parameters/ProjectTag" }, { "$ref": "#/components/parameters/Payment" }, { "$ref": "#/components/parameters/PaymentSignature" }, { "$ref": "#/components/parameters/PaymentRecovery" }, { "$ref": "#/components/parameters/DisclosureMax" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/LaneDowngrade" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" } } } }, "responses": { "422": { "description": "Idempotency-Key already used with a different canonical body or endpoint (idempotency_key_reused)." }, "200": { "description": "Results best first, with usage, cost and a signed receipt.", "headers": { "Idempotent-Replay": { "description": "true when the original kept result is returned, without another charge or receipt.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Anyroute-Disclosure": { "$ref": "#/components/headers/Disclosure" }, "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "Inference-Id": { "$ref": "#/components/headers/InferenceId" }, "X-Generation-Id": { "$ref": "#/components/headers/GenerationId" }, "X-Anyroute-Policy-Hash": { "$ref": "#/components/headers/PolicyHash" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/DisclosureUnavailable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/LaneNotAvailable" }, "503": { "$ref": "#/components/responses/DisclosureProviderDown" }, "default": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/teams": { "post": { "tags": [ "Teams" ], "operationId": "createTeam", "summary": "Create a team (organisation)", "description": "Management key. A team made by a wallet-signed-in account is owned by that wallet.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "budget_usd": { "type": [ "number", "null" ], "minimum": 0 } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "tags": [ "Teams" ], "operationId": "listTeams", "summary": "List teams", "description": "A management key lists its account's teams; a team key (viewer, dev, admin, owner) its own team. Agent keys get 403.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Teams.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{id}": { "get": { "tags": [ "Teams" ], "operationId": "getTeam", "summary": "Get a team", "description": "Viewer, dev, admin or owner.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." } ], "responses": { "200": { "description": "The team.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Team" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Teams" ], "operationId": "updateTeam", "summary": "Rename a team or set its org budget", "description": "Admin or owner. An org budget can be set only when every key in the team has a limit and the limits fit.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "budget_usd": { "type": [ "number", "null" ], "minimum": 0 } } } } } }, "responses": { "200": { "description": "The team.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "org_budget_exceeded, org_budget_limit_required or org_budget_unlimited_keys: the change does not fit the org budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/teams/{id}/members/{hash}": { "put": { "tags": [ "Teams" ], "operationId": "setTeamMember", "summary": "Add a key to a team or change its role", "description": "Admin or owner; never a role at or above your own unless you are the owner.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." }, { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The key's hash." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "dev", "member", "viewer", "agent" ] } } } } } }, "responses": { "200": { "description": "The membership.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "team": { "type": "string" }, "key_hash": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "dev", "member", "viewer", "agent" ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "org_budget_exceeded, org_budget_limit_required or org_budget_unlimited_keys: the change does not fit the org budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/teams/{id}/owner/challenge": { "post": { "tags": [ "Teams" ], "operationId": "teamOwnerChallenge", "summary": "Start binding the team to a wallet or Safe", "description": "Owner only. Returns a one-time message for the wallet or Safe to sign.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } } } } }, "responses": { "200": { "description": "The message to sign.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WalletChallenge" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{id}/owner": { "post": { "tags": [ "Teams" ], "operationId": "bindTeamOwner", "summary": "Bind the team to a wallet or Safe", "description": "Owner only. A wallet's signature is checked by recovery; a contract wallet's by EIP-1271: isValidSignature(hashMessage(message), signature) must return 0x1626ba7e, read on chain. The bound address then signs in as owner.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address", "nonce", "signature" ], "properties": { "address": { "type": "string" }, "nonce": { "type": "string" }, "signature": { "type": "string" } } } } } }, "responses": { "200": { "description": "The team.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{id}/invites": { "post": { "tags": [ "Teams" ], "operationId": "createTeamInvite", "summary": "Create a single-use invite", "description": "Admin or owner. The invite is shown once; only its SHA-256 is stored.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInviteRequest" } } } }, "responses": { "201": { "description": "The invite.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "invite": { "type": "string", "pattern": "^ar-inv-[0-9a-f]{48}$" }, "team": { "type": "string" }, "role": { "type": "string" }, "method": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/join/challenge": { "post": { "tags": [ "Teams" ], "operationId": "teamJoinChallenge", "summary": "Start joining a team with an invite", "description": "No key. Passkey: WebAuthn creation options (attestation none, a random user handle, no name or email). Wallet: a message to sign.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invite", "method" ], "properties": { "invite": { "type": "string" }, "method": { "type": "string", "enum": [ "passkey", "wallet" ] }, "address": { "type": "string" } } } } } }, "responses": { "200": { "description": "The challenge.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TeamChallenge" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/teams/join": { "post": { "tags": [ "Teams" ], "operationId": "joinTeam", "summary": "Join a team", "description": "No key. Send the passkey registration or the wallet signature. The invite and the challenge work once. Returns a 12-hour key for the new member.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invite", "challenge_id" ], "properties": { "invite": { "type": "string" }, "challenge_id": { "type": "string" }, "passkey": { "type": "object", "required": [ "id", "response" ], "properties": { "id": { "type": "string" }, "rawId": { "type": "string" }, "type": { "const": "public-key" }, "response": { "type": "object", "required": [ "clientDataJSON", "attestationObject" ], "properties": { "clientDataJSON": { "type": "string" }, "attestationObject": { "type": "string" } } } } }, "wallet": { "type": "object", "required": [ "address", "signature" ], "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "signature": { "type": "string" } } } } } } } }, "responses": { "201": { "description": "Joined.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSignedIn" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "already_member: that passkey or wallet is already in the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/teams/{id}/sign-in/challenge": { "post": { "tags": [ "Teams" ], "operationId": "teamSignInChallenge", "summary": "Start signing in to a team", "description": "No key. Passkey: WebAuthn request options with an empty allowCredentials (discoverable passkeys). Wallet: a message to sign.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "passkey", "wallet" ] }, "address": { "type": "string" } } } } } }, "responses": { "200": { "description": "The challenge.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TeamChallenge" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/teams/{id}/sign-in": { "post": { "tags": [ "Teams" ], "operationId": "teamSignIn", "summary": "Sign in to a team", "description": "No key. A passkey assertion (signature and a counter that must increase) or a wallet signature (EOA or EIP-1271). The owner's bound wallet or Safe signs in as owner. Returns a 12-hour key with a limit of 0.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challenge_id" ], "properties": { "challenge_id": { "type": "string" }, "passkey": { "type": "object", "required": [ "id", "response" ], "properties": { "id": { "type": "string" }, "rawId": { "type": "string" }, "type": { "const": "public-key" }, "response": { "type": "object", "required": [ "clientDataJSON", "authenticatorData", "signature" ], "properties": { "clientDataJSON": { "type": "string" }, "authenticatorData": { "type": "string" }, "signature": { "type": "string" }, "userHandle": { "type": [ "string", "null" ] } } } } }, "wallet": { "type": "object", "required": [ "address", "signature" ], "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "signature": { "type": "string" } } } } } } } }, "responses": { "201": { "description": "Signed in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSignedIn" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/teams/{id}/principals/{pid}": { "patch": { "tags": [ "Teams" ], "operationId": "updateTeamPrincipal", "summary": "Change a member's role, revoke or restore them", "description": "Admin or owner. Revoking disables every key issued to the member.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Member id (tp_...)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "dev", "viewer" ] }, "disabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The member.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TeamPrincipal" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Teams" ], "operationId": "revokeTeamPrincipal", "summary": "Revoke a member", "description": "Admin or owner. Disables the member and every key issued to it.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Member id (tp_...)." } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "type": "boolean" }, "keys_disabled": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{id}/audit": { "get": { "tags": [ "Teams" ], "operationId": "listTeamAudit", "summary": "Read the audit log", "description": "Viewer, dev, admin or owner. Entries in chain order.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "A page of entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "head", "next_after", "genesis" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamAuditEntry" } }, "head": { "type": "object", "properties": { "seq": { "type": "integer" }, "hash": { "type": "string" } } }, "next_after": { "type": [ "integer", "null" ] }, "genesis": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{id}/audit/roots": { "get": { "tags": [ "Teams" ], "operationId": "listTeamAuditRoots", "summary": "Hourly Merkle roots of the audit log", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." } ], "responses": { "200": { "description": "One root per UTC hour.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamAuditRoot" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{id}/audit/export": { "get": { "tags": [ "Teams" ], "operationId": "exportTeamAudit", "summary": "Export the audit log with its chain", "description": "Viewer, dev, admin or owner. JSONL: a header line, one entry per line, then one hourly root per line. CSV: team,seq,at,actor,action,target,detail,prev_hash,hash. Verify offline with node scripts/verify-audit.mjs .", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id (team_...)." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "jsonl", "csv" ], "default": "jsonl" } } ], "responses": { "200": { "description": "The export as a download.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=\"anyroute-audit-.jsonl\" (or .csv)" } }, "content": { "application/x-ndjson": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/status/slo": { "get": { "tags": [ "Status page" ], "operationId": "getStatusSlo", "summary": "Availability, latency and error budget per lane and surface", "description": "Public, cached for 30 seconds. For each privacy lane (public, attested, unlinkable) and each API surface (chat, embeddings, batch, messages, ollama, and rerank where served): availability over 1 hour, 24 hours, 7 days and 30 days, p50 and p95 latency over 24 hours, error counts by class, the SLO target, the 30-day error budget, 90 daily availability figures and the open and recent incidents. The public lane is summed from public-lane request outcomes in five-minute buckets. The attested and unlinkable lanes use only the differentially private hourly releases published at /api/v1/stats and say so with source: dp-noised; they share one set of noisy counters and have no per-surface breakdown.", "responses": { "200": { "description": "The SLO document.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/StatusSlo" } } } } } } } } }, "/api/v1/status/incidents": { "get": { "tags": [ "Status page" ], "operationId": "listStatusIncidents", "summary": "Confirmed incidents of the last 90 days", "description": "Public: confirmed incidents, newest first. With all=true and the operator token (ADMIN_TOKEN), also automatic suggestions and dismissed ones.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "all", "in": "query", "description": "Operator only.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Incidents.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatusIncident" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Status page" ], "operationId": "createStatusIncident", "summary": "Open an incident (operator)", "security": [ { "BearerAuth": [] } ], "description": "Operator only (ADMIN_TOKEN as Bearer or x-admin-token).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title", "lanes", "message" ], "properties": { "title": { "type": "string", "maxLength": 140 }, "lanes": { "type": "array", "items": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] }, "minItems": 1 }, "surfaces": { "type": "array", "items": { "type": "string", "enum": [ "chat", "embeddings", "batch", "messages", "ollama", "rerank" ] } }, "impact": { "type": "string", "enum": [ "none", "minor", "major", "critical" ], "default": "minor" }, "status": { "type": "string", "enum": [ "investigating", "identified", "monitoring" ], "default": "investigating" }, "message": { "type": "string", "maxLength": 2000 }, "started_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "The incident.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/StatusIncident" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/status/incidents/{id}": { "get": { "tags": [ "Status page" ], "operationId": "getStatusIncident", "summary": "One confirmed incident", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The incident.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/StatusIncident" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Status page" ], "operationId": "patchStatusIncident", "summary": "Change an incident's title, impact, lanes or surfaces (operator)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 140 }, "lanes": { "type": "array", "items": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] }, "minItems": 1 }, "surfaces": { "type": "array", "items": { "type": "string", "enum": [ "chat", "embeddings", "batch", "messages", "ollama", "rerank" ] } }, "impact": { "type": "string", "enum": [ "none", "minor", "major", "critical" ] } } } } } }, "responses": { "200": { "description": "The incident.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/StatusIncident" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/status/incidents/{id}/updates": { "post": { "tags": [ "Status page" ], "operationId": "postStatusIncidentUpdate", "summary": "Post a status update (operator)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Adds an update and moves the incident to its status. On an automatic suggestion, investigating, identified or monitoring confirms it (it becomes public) and dismissed drops it. resolved and dismissed are final: a later update is refused with 409.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "message" ], "properties": { "status": { "type": "string", "enum": [ "investigating", "identified", "monitoring", "resolved", "dismissed" ] }, "message": { "type": "string", "maxLength": 2000 }, "impact": { "type": "string", "enum": [ "none", "minor", "major", "critical" ] } } } } } }, "responses": { "200": { "description": "The incident.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/StatusIncident" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The incident is closed, or only a suggestion can be dismissed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/status/incidents.atom": { "get": { "tags": [ "Status page" ], "operationId": "getStatusIncidentsAtom", "summary": "Incidents as an Atom feed", "responses": { "200": { "description": "Atom 1.0 feed of confirmed incidents.", "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } }, "/api/v1/status/incidents.rss": { "get": { "tags": [ "Status page" ], "operationId": "getStatusIncidentsRss", "summary": "Incidents as an RSS feed", "responses": { "200": { "description": "RSS 2.0 feed of confirmed incidents.", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } } } }, "/api/v1/characters": { "get": { "tags": [ "Characters" ], "operationId": "listCharacters", "summary": "Discover public characters, or list your own", "description": "With no key: public characters only, newest first, filtered by tag and a text search over name, tags and creator. With ?mine=1 and a key: the caller's own characters of every visibility.", "security": [ {}, { "BearerAuth": [] } ], "parameters": [ { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Text search over name, tags and creator." }, { "name": "mine", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "The caller's own characters; needs a key." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Characters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Character" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Characters" ], "operationId": "createCharacter", "summary": "Create a character from a card", "description": "Send a Tavern card as JSON (card) or a PNG that carries one (png). A private card is encrypted on the client with sealCard from @anyroute/client/characters: send sealed_card and card_hash, and the router keeps only the ciphertext and the hash.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CharacterInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Character" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "character_limit_reached: the account keeps the most characters it may. Delete one first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "payload_too_large: the PNG is over 8 MB, or the card is over the size limit as JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/characters/{id}": { "get": { "tags": [ "Characters" ], "operationId": "getCharacter", "summary": "Get a character", "description": "Public and unlisted characters to anyone with the id. A private one only to its owner, with sealed_card; to anyone else it is a 404.", "security": [ {}, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "description": "The character id, as in @character/." } ], "responses": { "200": { "description": "The character.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Character" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Characters" ], "operationId": "updateCharacter", "summary": "Replace a character's card, visibility or default model", "description": "Owner only. The same body as POST; the card_hash changes with the card.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "description": "The character id, as in @character/." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CharacterInput" } } } }, "responses": { "200": { "description": "The updated character.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Character" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "payload_too_large: the PNG is over 8 MB, or the card is over the size limit as JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Characters" ], "operationId": "deleteCharacter", "summary": "Delete a character", "description": "Owner only. Calls to @character/ fail from then on; receipts of past calls are unaffected.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "description": "The character id, as in @character/." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string" }, "deleted": { "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/characters/{id}/export": { "get": { "tags": [ "Characters" ], "operationId": "exportCharacter", "summary": "Download the card as JSON or PNG", "description": "Public and unlisted characters. The PNG carries the card in a chara tEXt chunk (spec v2) or in both ccv3 and chara (spec v3), so SillyTavern and other card tools import it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "description": "The character id, as in @character/." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "png" ], "default": "json" } }, { "name": "spec", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "v2", "v3" ] }, "description": "Defaults to the card's own spec." } ], "responses": { "200": { "description": "The card file.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=\".json\" (or .png)" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CharacterCard" } }, "image/png": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/characters/{id}/greetings": { "get": { "tags": [ "Characters" ], "operationId": "getCharacterGreetings", "summary": "The greetings a chat can open with", "description": "first_mes, then the alternate greetings. The index is what the chat endpoint's greeting field takes.", "security": [ {}, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "description": "The character id, as in @character/." } ], "responses": { "200": { "description": "The greetings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "greetings" ], "properties": { "greetings": { "type": "array", "items": { "type": "string" } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/characters/{id}/usage": { "get": { "tags": [ "Characters" ], "operationId": "getCharacterUsage", "summary": "Calls and cost per day, for the card's creator", "description": "Owner only. Creator attribution for a public card: how many calls used it and what they cost, per day. Never the content of a call, and never who made it.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "description": "The character id, as in @character/." } ], "responses": { "200": { "description": "Usage per day, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CharacterUsage" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/characters/{id}/chat": { "post": { "tags": [ "Characters" ], "operationId": "characterChat", "summary": "Chat with a character", "description": "A chat completion with the character's card as the prompt. The model is model, then models[0], then the card's default model. The lane defaults to attested when the model has an attested provider, else public; a request's own provider.lane wins, and a lane that cannot be served fails as on /chat/completions. Budgets, guardrails and signed receipts apply as there. Memory sent in memory is used for this call only and never stored. For a private card, send the decrypted card: without it the call fails with 400 card_required, and a card that does not hash to card_hash with 409 card_hash_mismatch. A character with no default model and no model in the request fails with 400 model_required.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "description": "The character id, as in @character/." }, { "$ref": "#/components/parameters/Lane" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CharacterChatRequest" } } } }, "responses": { "200": { "description": "A chat completion, or SSE events followed by data: [DONE] when stream is true.", "headers": { "X-Anyroute-Character": { "description": "The character id that answered.", "schema": { "type": "string" } }, "X-Anyroute-Character-Lane": { "description": "The lane the character call ran on.", "schema": { "type": "string", "enum": [ "attested", "public" ] } }, "X-Anyroute-Character-Note": { "description": "Present when the attested lane was not available for this model, in plain English.", "schema": { "type": "string" } }, "X-Anyroute-Lane": { "$ref": "#/components/headers/LaneServed" }, "X-Receipt-Id": { "$ref": "#/components/headers/ReceiptId" }, "X-Anyroute-Character-Session": { "description": "The session_id the request sent, echoed back.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAI chat completion." } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "card_hash_mismatch: the decrypted card sent for a private character does not hash to its card_hash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "no_attested_endpoint: the request asked for the attested lane and no attested endpoint can serve the model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/characters/group/next": { "post": { "tags": [ "Characters" ], "operationId": "characterGroupNext", "summary": "Pick who speaks next in a group chat", "description": "Returns the member that should answer next; call its chat endpoint with the same messages. Nothing is stored.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CharacterGroupNextRequest" } } } }, "responses": { "200": { "description": "The next speaker.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "next", "index" ], "properties": { "next": { "type": "string" }, "index": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/memory": { "get": { "tags": [ "Memory" ], "operationId": "listMemory", "summary": "List memory entries (metadata only)", "description": "The caller's entries, optionally for one scope, without the sealed values.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entries and their total size.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total_bytes" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryEntry" } }, "total_bytes": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Memory" ], "operationId": "createMemory", "summary": "Store a sealed memory entry", "description": "The client encrypts the entry and derives the scope; the router stores the ciphertext and cannot read it or tell which character it is for. An embedding is stored only with embedding_opt_in: true, because a vector is derived from the text and can leak its topic.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryInput" } } } }, "responses": { "201": { "description": "Stored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MemoryEntry" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "description": "The entry, or the caller's memory in total, is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Memory" ], "operationId": "deleteMemoryScope", "summary": "Delete every entry in a scope", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "scope": { "type": "string" }, "deleted": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/memory/{id}": { "get": { "tags": [ "Memory" ], "operationId": "getMemory", "summary": "Read one sealed memory entry", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The memory entry id." } ], "responses": { "200": { "description": "The entry with its sealed value.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MemoryEntry" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Memory" ], "operationId": "updateMemory", "summary": "Replace a sealed memory entry", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The memory entry id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryInput" } } } }, "responses": { "200": { "description": "Replaced.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MemoryEntry" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "The entry is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Memory" ], "operationId": "deleteMemory", "summary": "Delete a memory entry", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The memory entry id." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/memory/search": { "post": { "tags": [ "Memory" ], "operationId": "searchMemory", "summary": "Nearest sealed entries to an embedding", "description": "Searches only entries stored with embedding_opt_in. Returns the sealed values for the client to decrypt.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemorySearchRequest" } } } }, "responses": { "200": { "description": "The nearest entries, best first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "score", "kind", "sealed" ], "properties": { "id": { "type": "string" }, "score": { "type": "number" }, "kind": { "type": "string" }, "sealed": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/skills": { "get": { "tags": [ "Skills" ], "operationId": "listSkills", "summary": "Search the skills registry", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Matches name, description, author and slug." }, { "name": "level", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated scan levels: trusted, caution, dangerous." }, { "name": "include_revoked", "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Skills, trusted first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SkillSummary" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "download_levels": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/skills/import": { "post": { "tags": [ "Skills" ], "operationId": "importSkill", "summary": "Import a skill from a git repository or an archive; it is hashed and scanned", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "price_usd", "in": "query", "schema": { "type": "number", "minimum": 0 }, "description": "For an archive body: the install price." }, { "name": "path", "in": "query", "schema": { "type": "string" }, "description": "For an archive body: the skill's folder inside the archive." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Exactly one of git or archive.", "properties": { "git": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "description": "https:// only." }, "ref": { "type": "string" }, "path": { "type": "string" } } }, "archive": { "type": "string", "contentEncoding": "base64", "description": "A .tar.gz, .tar or .zip of the skill folder." }, "path": { "type": "string" }, "price_usd": { "type": "number", "minimum": 0, "maximum": 10000 } } } }, "application/gzip": { "schema": { "type": "string", "format": "binary" } }, "application/x-tar": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The same files were already imported; the existing skill.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Skill" } } } } } }, "201": { "description": "Imported and scanned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Skill" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/skills/{id}": { "get": { "tags": [ "Skills" ], "operationId": "getSkill", "summary": "A skill: manifest, files, content hash, scan report, price and chain fields", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sk_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "The skill.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Skill" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Skills" ], "operationId": "updateSkill", "summary": "Change a skill's price (the publishing account)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sk_[0-9a-f]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "price_usd" ], "properties": { "price_usd": { "type": "number", "minimum": 0, "maximum": 10000 } } } } } }, "responses": { "200": { "description": "The skill.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Skill" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/skills/{id}/download": { "get": { "tags": [ "Skills" ], "operationId": "downloadSkill", "summary": "Download the canonical tar.gz (trusted and caution skills only; paid skills after an install)", "description": "Returns 403 with the scan report for a dangerous or revoked skill. A paid skill needs the key of its author or of an account that installed it (402 otherwise). X-Skill-Content-Hash carries the sha256 of the uncompressed tar.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sk_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "The gzipped canonical tar.", "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/skills/{id}/install": { "post": { "tags": [ "Skills" ], "operationId": "installSkill", "summary": "Install a skill: a paid one debits the key's balance, 90% to the author and 10% network fee, with a signed receipt", "description": "Idempotent per skill and account: a repeat returns the first install and receipt (200) without a second charge.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sk_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "Already installed by this account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SkillInstall" } } } } } }, "201": { "description": "Installed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SkillInstall" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/skills/{id}/revoke": { "post": { "tags": [ "Skills" ], "operationId": "revokeSkill", "summary": "Revoke a skill (operator)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sk_[0-9a-f]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 280 } } } } } }, "responses": { "200": { "description": "The revoked skill.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Skill" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/network/policy": { "get": { "tags": [ "Network host policy" ], "description": "Public when NETWORK_POLICY_ENABLED is true (default false; requires TLOG_ENABLED). No policy is seeded. Includes canonical JSON, SHA-256, detached Ed25519 signature and public log verifier key. Pin the verifier key independently and verify the host_policy inclusion proof under a signed checkpoint with independent witness or public-log evidence. Publication does not change existing provider admission. Current sidecars do not bind a source hash, engine image or model ID; missing bindings fail the pure check. AnyRoute reads request text in memory on every lane.", "responses": { "200": { "description": "Published host policy.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/HostPolicyPublication" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "getCurrentNetworkHostPolicy", "summary": "Current signed network host policy" } }, "/api/v1/network/policy/{version}": { "get": { "tags": [ "Network host policy" ], "description": "Public when NETWORK_POLICY_ENABLED is true (default false; requires TLOG_ENABLED). No policy is seeded. Includes canonical JSON, SHA-256, detached Ed25519 signature and public log verifier key. Pin the verifier key independently and verify the host_policy inclusion proof under a signed checkpoint with independent witness or public-log evidence. Publication does not change existing provider admission. Current sidecars do not bind a source hash, engine image or model ID; missing bindings fail the pure check. AnyRoute reads request text in memory on every lane.", "responses": { "200": { "description": "Published host policy.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/HostPolicyPublication" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "operationId": "getNetworkHostPolicyVersion", "summary": "An immutable signed network host policy version", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ] } }, "/trpc/network.publishPolicy": { "post": { "tags": [ "Network host policy" ], "operationId": "publishNetworkHostPolicy", "summary": "Publish a consecutive signed host policy version (operator)", "security": [ { "AdminToken": [] } ], "description": "POST /trpc/network.publishPolicy accepts the policy document directly as a tRPC JSON input. Requires ADMIN_TOKEN as x-admin-token or Authorization: Bearer, NETWORK_POLICY_ENABLED and TLOG_ENABLED. The policy, host_policy log leaf and signed checkpoint commit atomically. Versions start at 1 and advance consecutively; exact resubmission is idempotent, replacement is refused. Issue time cannot be in the future or before the preceding version. allow_dev must be false. Existing providers are unaffected. This publication path is groundwork for later host signup; it does not open signup.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostPolicy" } } } }, "responses": { "200": { "description": "tRPC publication result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HostPolicyPublication" } } } } } } } }, "default": { "description": "tRPC error envelope: unauthorized without the operator token, precondition failed when disabled, conflict for an occupied or nonconsecutive version, or bad request for invalid policy or issue time.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" } } } } } } } } }, "/api/v1/e2ee/sessions/{id}": { "get": { "summary": "Proxy content-addressed gateway upstream session", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "responses": { "200": { "description": "ACI session whose canonical hash must match its id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "description": "Gateway session unavailable." } } } }, "/api/v1/e2ee/chat/completions": { "post": { "summary": "End-to-end encrypted chat (Phala gateway)", "description": "Off by default (E2EE_PASSTHROUGH_ENABLED=false). Exact JSON bytes and encrypted fields are forwarded unchanged; SSE bytes pass through unchanged. Message content is restored inside the attested gateway enclave, which forwards it to the serving workload over a separate confidential channel. Model, sizes, timing, public keys and payment metadata remain visible. Only the phala-confidential-ai provider and text chat are supported; tools, files, search and unknown fields are refused. Holds use a conservative input-byte bound plus max_tokens. Charges trust gateway-reported usage; completion or truncation without usage charges the hold. The router cannot check the restored plaintext request hash; clients must independently verify attestation and complete signed wire receipts. Prepaid keys and blind tokens are supported.", "parameters": [ { "$ref": "#/components/parameters/ProjectTag" }, { "in": "header", "name": "X-E2EE-Version", "required": true, "schema": { "type": "string" }, "description": "Exactly 2." }, { "in": "header", "name": "X-Client-Pub-Key", "required": true, "schema": { "type": "string" }, "description": "Client X25519 public key, 32-byte hex." }, { "in": "header", "name": "X-Model-Pub-Key", "required": true, "schema": { "type": "string" }, "description": "Attestation-bound gateway X25519 key, 32-byte hex." }, { "in": "header", "name": "X-E2EE-Nonce", "required": true, "schema": { "type": "string" }, "description": "Fresh 32-byte replay nonce, 64 hex characters." }, { "in": "header", "name": "X-E2EE-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds within 300 seconds." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "messages", "max_tokens", "provider" ], "properties": { "model": { "type": "string" }, "messages": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant" ] }, "content": { "type": "string", "pattern": "^(?:[0-9a-f]{2}){60,}$", "description": "v2 X25519 field ciphertext." } } } }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 32768 }, "stream": { "type": "boolean" }, "stream_options": { "type": "object", "additionalProperties": false, "required": [ "include_usage" ], "properties": { "include_usage": { "const": true } } }, "provider": { "type": "object", "additionalProperties": false, "required": [ "aci_verified", "zdr" ], "properties": { "aci_verified": { "const": true }, "zdr": { "const": true }, "aci_session_ids": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } }, "n": { "const": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 } } } } } }, "responses": { "200": { "description": "Encrypted JSON or SSE, with X-Receipt-Id, X-Anyroute-Lane and X-E2EE-Receipt-Id. Stream completion is provisional until signed gateway evidence verifies.", "content": { "application/json": { "schema": { "type": "object" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "Envelope exceeds 1 MiB." }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "description": "Gateway rejection or E2EE transport failure." }, "503": { "description": "Configured provider or fresh attestation unavailable." } }, "security": [ { "BearerAuth": [] }, { "PrivateToken": [] } ] } }, "/api/v1/e2ee/attestation": { "get": { "summary": "Proxy gateway attestation for independent client verification", "description": "Off by default. The client supplies its own fresh nonce and must verify the TDX quote, keyset binding, measurements, freshness, event log and deployment policy itself. A router boolean is not proof.", "parameters": [ { "in": "query", "name": "nonce", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "responses": { "200": { "description": "Unmodified attestation document fields.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "description": "Gateway evidence unavailable." }, "503": { "description": "Provider unavailable." } } } }, "/api/v1/e2ee/receipts/{id}": { "get": { "summary": "Proxy signed gateway receipt", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" } } ], "responses": { "200": { "description": "Signed ACI receipt for independent client verification.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "description": "Gateway evidence unavailable." } } } }, "/api/v1/network/bonds": { "get": { "tags": [ "Network" ], "summary": "Public HostBond work deposit summary", "description": "Available when NETWORK_BONDS_ENABLED is on. Canonical public chain amounts in six-decimal USDG base units; includes index freshness. A work deposit supplies bounded routing priority, subject to health, probation, attestation and lane checks.", "responses": { "200": { "description": "Bond summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "contract": { "type": "string" }, "chain_id": { "type": "integer" }, "asset": { "type": "string" }, "decimals": { "type": "integer" }, "indexed_block": { "type": [ "string", "null" ] }, "fresh": { "type": "boolean" }, "minimum_units": { "type": "string" }, "total_units": { "type": "string" }, "active_units": { "type": "string" }, "hosts": { "type": "integer" }, "pending_slashes": { "type": "integer" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/me/record-certificate": { "post": { "tags": [ "Agents" ], "summary": "Issue a signed track-record certificate", "description": "Signed by AnyRoute's router, which sees the agent's activity; not a zero-knowledge proof. Requests through AnyRoute only; no on-chain enforcement. AGENT_POLICY_ENABLED gates availability; TLOG_ENABLED is required for issuance. Fresh random pseudonym; no agent key hash or account id. Shared issuer key, claims and timing may correlate certificates. Five issuance attempts per account per minute. No certificates or prompt text are stored by this path. Later events do not revoke the seven-day snapshot.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "claims" ], "properties": { "claims": { "$ref": "#/components/schemas/AgentRecordClaims" } } } } } }, "responses": { "200": { "description": "Certificate result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentRecordCertificate" } } } } } }, "400": { "description": "Invalid claim request.", "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Feature disabled.", "$ref": "#/components/responses/NotFound" }, "422": { "description": "Any claim false or insufficient retained history; no partial certificate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Account issuance limit exceeded; Retry-After header.", "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Signing key log unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "issueAgentRecordCertificate" } }, "/api/v1/agents/certificates/verify": { "post": { "tags": [ "Agents" ], "summary": "Verify a track-record certificate", "description": "Public when AGENT_POLICY_ENABLED is on. Checks shape, signature, issuer-key issuance window and expiry, not underlying observations. Signed by AnyRoute's router, which sees the agent's activity; not a zero-knowledge proof.", "security": [], "responses": { "200": { "description": "Certificate result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "valid", "notice" ], "properties": { "valid": { "type": "boolean" }, "notice": { "type": "string" } } } } } } } }, "400": { "description": "Malformed certificate.", "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Feature disabled.", "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRecordCertificate" } } } }, "operationId": "verifyAgentRecordCertificate" }, "get": { "tags": [ "Agents" ], "summary": "Verify a track-record certificate", "description": "Public when AGENT_POLICY_ENABLED is on. Checks shape, signature, issuer-key issuance window and expiry, not underlying observations. Signed by AnyRoute's router, which sees the agent's activity; not a zero-knowledge proof.", "security": [], "responses": { "200": { "description": "Certificate result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "valid", "notice" ], "properties": { "valid": { "type": "boolean" }, "notice": { "type": "string" } } } } } } } }, "400": { "description": "Malformed certificate.", "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Feature disabled.", "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "certificate", "in": "query", "required": true, "description": "URL-encoded certificate JSON. Prefer POST to avoid URL retention outside the router.", "schema": { "type": "string", "maxLength": 8192 } } ], "operationId": "verifyAgentRecordCertificateQuery" } }, "/api/v1/agents/profiles": { "get": { "operationId": "agentDirectory", "tags": [ "Agent rulebook" ], "summary": "Discover opt-in public agents", "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing. Disabled or expired keys are hidden. MCP anyroute_agent_directory accepts the same arguments without authentication. Exact tag match; ascending slug cursor pagination.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "url", "capabilities", "provider", "anyroute" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 280 }, "url": { "type": "string", "format": "uri", "description": "Public profile page, not invocation endpoint." }, "homepage": { "type": "string", "format": "uri", "maxLength": 500, "description": "HTTP(S) only, without embedded credentials." }, "endpoint": { "type": "string", "format": "uri", "maxLength": 500, "description": "Owner-declared HTTPS agent endpoint, when set." }, "capabilities": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "provider": { "type": "object", "properties": { "organization": { "const": "AnyRoute" } }, "required": [ "organization" ] }, "anyroute": { "type": "object", "required": [ "id", "rulebook_summary", "certificates", "status", "notice" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" }, "rulebook_summary": { "type": "object", "additionalProperties": false, "properties": { "has_spending_caps": { "type": "boolean" }, "asks_before_spending": { "type": "boolean" }, "kill_switch_armed": { "type": "boolean" }, "killed": { "type": "boolean" } } }, "certificates": { "type": "array", "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "payload", "key_id", "signature", "valid" ], "properties": { "key_id": { "type": "string", "pattern": "^[0-9a-f]{16}$" }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "type", "pseudonym", "claims", "issued_at", "expires_at", "notice" ], "properties": { "version": { "const": 1 }, "type": { "const": "anyroute.agent.record-certificate" }, "pseudonym": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "claims": { "$ref": "#/components/schemas/AgentRecordClaims" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Exactly seven days after issuance." }, "notice": { "const": "Signed by AnyRoute's router, which sees the agent's activity; not a zero-knowledge proof." } } }, "valid": { "const": true, "description": "Router read-time validity metadata; remove this field before submitting the certificate to strict certificate verifiers." } } } }, "status": { "type": "object", "properties": { "sealed": { "const": "unavailable" }, "attested": { "const": "unavailable" } } }, "notice": { "type": "string" }, "identity": { "description": "AGENT_IDENTITY_ENABLED only. Either {opted_out: true} or links: card, receipt_keys (/.well-known/anyroute-receipt-keys.json), receipt_key_id, registration (ERC-8004 registration file or null) and erc8004 {registry, agent_id, status}.", "type": "object" }, "liveness": { "description": "AGENT_IDENTITY_ENABLED only. endpoint_declared, live (true, false or null before the first probe), probed_at, http_status and the probe receipt signed with the router's receipt key.", "type": "object" }, "track_record": { "description": "AGENT_IDENTITY_ENABLED only. The newest published, unexpired track record: id, url, stats, merkle_root, expires_at; or null.", "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "reputation": { "description": "PAID_FEEDBACK_ENABLED only. {opted_in: false, url} or opted_in, score (0 to 100 or null), feedback_count, weight_usd, by_kind, half_life_days and url.", "type": "object" } } } } } }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" }, { "type": "null" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "tag", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ] } }, "/api/v1/agents/profiles/{slug}": { "get": { "operationId": "publicAgentCard", "tags": [ "Agent rulebook" ], "summary": "Read an A2A-style public agent card", "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description", "url", "capabilities", "provider", "anyroute" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 280 }, "url": { "type": "string", "format": "uri", "description": "Public profile page, not invocation endpoint." }, "homepage": { "type": "string", "format": "uri", "maxLength": 500, "description": "HTTP(S) only, without embedded credentials." }, "endpoint": { "type": "string", "format": "uri", "maxLength": 500, "description": "Owner-declared HTTPS agent endpoint, when set." }, "payout_wallet": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "Owner-declared USDG wallet that other agents pay directly, when set." }, "capabilities": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "provider": { "type": "object", "properties": { "organization": { "const": "AnyRoute" } }, "required": [ "organization" ] }, "anyroute": { "type": "object", "required": [ "id", "rulebook_summary", "certificates", "status", "notice" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" }, "rulebook_summary": { "type": "object", "additionalProperties": false, "properties": { "has_spending_caps": { "type": "boolean" }, "asks_before_spending": { "type": "boolean" }, "kill_switch_armed": { "type": "boolean" }, "killed": { "type": "boolean" } } }, "certificates": { "type": "array", "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "payload", "key_id", "signature", "valid" ], "properties": { "key_id": { "type": "string", "pattern": "^[0-9a-f]{16}$" }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "type", "pseudonym", "claims", "issued_at", "expires_at", "notice" ], "properties": { "version": { "const": 1 }, "type": { "const": "anyroute.agent.record-certificate" }, "pseudonym": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "claims": { "$ref": "#/components/schemas/AgentRecordClaims" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Exactly seven days after issuance." }, "notice": { "const": "Signed by AnyRoute's router, which sees the agent's activity; not a zero-knowledge proof." } } }, "valid": { "const": true, "description": "Router read-time validity metadata; remove this field before submitting the certificate to strict certificate verifiers." } } } }, "status": { "type": "object", "properties": { "sealed": { "const": "unavailable" }, "attested": { "const": "unavailable" } } }, "notice": { "type": "string" }, "identity": { "description": "AGENT_IDENTITY_ENABLED only. Either {opted_out: true} or links: card, receipt_keys (/.well-known/anyroute-receipt-keys.json), receipt_key_id, registration (ERC-8004 registration file or null) and erc8004 {registry, agent_id, status}.", "type": "object" }, "liveness": { "description": "AGENT_IDENTITY_ENABLED only. endpoint_declared, live (true, false or null before the first probe), probed_at, http_status and the probe receipt signed with the router's receipt key.", "type": "object" }, "track_record": { "description": "AGENT_IDENTITY_ENABLED only. The newest published, unexpired track record: id, url, stats, merkle_root, expires_at; or null.", "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "reputation": { "description": "PAID_FEEDBACK_ENABLED only. {opted_in: false, url} or opted_in, score (0 to 100 or null), feedback_count, weight_usd, by_kind, half_life_days and url.", "type": "object" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" } } ] } }, "/api/v1/agents/{key_hash}/profile": { "get": { "operationId": "agentProfileSettings", "tags": [ "Agent rulebook" ], "summary": "Read owned profile publication settings", "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 280 }, "homepage": { "type": "string", "format": "uri", "maxLength": 500, "description": "HTTP(S) only, without embedded credentials." }, "capabilities": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "default": [] }, "show": { "type": "array", "maxItems": 3, "items": { "type": "string", "enum": [ "spending_caps", "ask_first", "kill_switch" ] }, "default": [] }, "certificate_claims": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^(requests_at_least|no_denials_days|no_kills_days|active_days_at_least):[1-9][0-9]{0,14}$" }, "default": [], "description": "Absence claims limited to 90 days. Verified against this key, never accepted from another certificate." }, "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ApiError" }, "422": { "$ref": "#/components/responses/ApiError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ApiError" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "operationId": "publishAgentProfile", "tags": [ "Agent rulebook" ], "summary": "Publish selected public agent fields", "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing. Updates preserve the slug and replace all public fields and certificate selection. Empty claims remove the certificate. Issuance shares the account five-per-minute certificate limit.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" }, "url": { "type": "string", "format": "uri" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ApiError" }, "422": { "$ref": "#/components/responses/ApiError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ApiError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "description" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 280 }, "homepage": { "type": "string", "format": "uri", "maxLength": 500, "description": "HTTP(S) only, without embedded credentials." }, "endpoint": { "type": "string", "format": "uri", "maxLength": 500, "description": "Optional HTTPS agent endpoint without credentials or fragment. With AGENT_IDENTITY_ENABLED on, the agent-liveness job sends it one GET a day." }, "payout_wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Optional USDG wallet on Robinhood Chain that other agents pay directly (stored lowercase; not the zero address). Payments go wallet to wallet; Anyroute never holds the money." }, "capabilities": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "default": [] }, "show": { "type": "array", "maxItems": 3, "items": { "type": "string", "enum": [ "spending_caps", "ask_first", "kill_switch" ] }, "default": [] }, "certificate_claims": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^(requests_at_least|no_denials_days|no_kills_days|active_days_at_least):[1-9][0-9]{0,14}$" }, "default": [], "description": "Absence claims limited to 90 days. Verified against this key, never accepted from another certificate." } } } } } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "operationId": "unpublishAgentProfile", "tags": [ "Agent rulebook" ], "summary": "Delete owned public profile", "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing. Deletes the row immediately. Public reader copies and database backups may remain. Republish allocates a new slug.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "const": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ApiError" }, "422": { "$ref": "#/components/responses/ApiError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ApiError" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/agents/{key_hash}/sealed": { "post": { "tags": [ "Agents" ], "operationId": "postAgentSealed", "summary": "Register and verify sealed agent hosting", "description": "Requires principal ownership. AGENT_SEALED_ENABLED defaults to false and requires AGENT_POLICY_ENABLED plus a configured dstack or phala verifier. Measured code is not audited code; the router reads ordinary requests in memory. An owner may retain a credential copy; the badge does not prove each subsequent request originated in this VM. GET agent list and /api/v1/agents/me gain an optional sealed status when enabled; success expires after 30 minutes and clears on a failed check.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "Current registration status. Success requires fresh hardware quote, pinned TLS key, matching key fingerprint and verifier-recovered approved compose hash.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "attested", "agent_image_digest", "compose_hash", "checked_at", "expires_at" ], "properties": { "attested": { "type": "boolean" }, "agent_image_digest": { "type": "string" }, "compose_hash": { "type": "string" }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": "string" }, "verified_by": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Attestation failed or a concurrent registration replaced this one; data contains an unattested status or null.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "attested", "agent_image_digest", "compose_hash", "checked_at", "expires_at" ], "properties": { "attested": { "type": "boolean" }, "agent_image_digest": { "type": "string" }, "compose_hash": { "type": "string" }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": "string" }, "verified_by": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "attestation_url", "agent_image_digest", "compose_hash" ], "properties": { "attestation_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS /attest URL with no credentials, query or fragment." }, "agent_image_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "compose_hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } } } } } } }, "delete": { "tags": [ "Agents" ], "operationId": "deleteAgentSealed", "summary": "Remove sealed agent registration", "description": "Requires principal ownership. AGENT_SEALED_ENABLED defaults to false and requires AGENT_POLICY_ENABLED plus a configured dstack or phala verifier. Measured code is not audited code; the router reads ordinary requests in memory. An owner may retain a credential copy; the badge does not prove each subsequent request originated in this VM. GET agent list and /api/v1/agents/me gain an optional sealed status when enabled; success expires after 30 minutes and clears on a failed check.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "Registration deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/telegram/weekly-summary": { "get": { "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Weekly summary preference.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "opted_in", "last_sent_week" ], "properties": { "opted_in": { "type": "boolean", "default": false }, "last_sent_week": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-W[0-9]{2}$" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "This principal has no Telegram link." } }, "summary": "Read weekly Telegram summary preference", "description": "B120: WEEKLY_SUMMARY_ENABLED defaults false and requires Telegram linking and agent policies. Same principal auth as /api/v1/telegram/link, no-store. Preference belongs to this key’s link; last_sent_week is account-wide and survives unlink. One message/account for the previous ISO week, Monday from 09:00 UTC, hourly checks. Quiet weeks skipped; team administrators see only their team. Existing call charges, approval request statuses at send time, stop events and most-used model; top five agents by spend. Telegram can read names and totals. A crash or ambiguous network failure after sending but before commit may repeat delivery; no catch-up after Monday." }, "put": { "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Weekly summary preference.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "opted_in", "last_sent_week" ], "properties": { "opted_in": { "type": "boolean", "default": false }, "last_sent_week": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-W[0-9]{2}$" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "This principal has no Telegram link." }, "400": { "$ref": "#/components/responses/BadRequest" } }, "summary": "Choose weekly Telegram summaries", "description": "B120: Same auth and flag guards as GET. Updates only this principal’s existing Telegram link; opt-in defaults off. Unlink removes the preference. No-store. Strict boolean body; invalid bodies return 400.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "opted_in" ], "properties": { "opted_in": { "type": "boolean" } } } } } } } }, "/api/v1/telegram/link": { "get": { "summary": "Read Telegram link status", "description": "TELEGRAM_LINKING_ENABLED defaults false. Requires AGENT_POLICY_ENABLED and TELEGRAM_BOT_TOKEN. Management or owner/admin principal only, excluding session keys. Returns this key’s link status, Telegram user id and linked timestamp. No-store.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Telegram link status or single-use code." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "summary": "Issue a Telegram account link code", "description": "Same principal permissions as status. Returns code and expires_at. Valid five minutes, single-use, five issuance attempts per account per minute. Replaces the previous account code. Send /link privately to the bot; no API key needed in Telegram. Treat the code as an approval credential. No-store.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Telegram link status or single-use code." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "summary": "Unlink Telegram or cancel a pending code", "description": "Removes this principal’s Telegram link, its approval delivery markers and the account’s pending code. /unlink works from the bot. Stops account-link delivery; chat keys connected through /key remain separate until /forget. No-store.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Telegram link status or single-use code." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/tools/call": { "post": { "tags": [ "Paid tools" ], "operationId": "callPaidTool", "summary": "Pay an x402 tool from the key's balance", "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at anyroute.tech yet; every route answers 404 while it is off. See /docs/#paid-tools. The router fetches the resource unpaid and reads its 402 (x402 v1 JSON body with accepts, or the v2 PAYMENT-REQUIRED header). It pays only scheme exact in USDG on Robinhood Chain. A quote above max_price (the seller's price plus the router's take, TOOLS_TAKE_BPS), above TOOLS_MAX_PRICE_USD or outside the key's rulebook (tools.allow, tools.deny, tools.max_price_per_call, tools.daily_budget, caps, approval) is refused before anything is held or paid. Otherwise it holds price plus take, signs an EIP-3009 TransferWithAuthorization from the router's buyer wallet to the seller's payTo and retries with X-PAYMENT or PAYMENT-SIGNATURE. A 2xx JSON or plain-text answer of at most 2 MB is charged once and returned as untrusted data with a signed tool.call receipt (COSE_Sign1; check it with POST /api/v1/receipts/verify). Any other answer is not charged: the hold is released once the authorization expires unused, or the call is charged if the seller collected it anyway. then hands the answer to a model and needs tools.pass_to_models in the rulebook.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallRequest" } } } }, "responses": { "200": { "description": "The tool's answer, the charge and the tool.call receipt", "headers": { "X-Anyroute-Tool-Call": { "schema": { "type": "string" }, "description": "The call id." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ToolCall" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "tool_price_above_max, tool_price_above_router_max, tool_delisted or tool_pay_to_mismatch; nothing was charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "tool_not_payable or tool_content_type_refused; nothing was charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "description": "tool_seller_failed, tool_response_refused or tool_unreachable; not charged unless the seller later collects the authorization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "tools_buyer_unconfigured or tools_daily_limit; nothing was charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "tool_timeout before any payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/tools": { "get": { "tags": [ "Paid tools" ], "operationId": "listPaidTools", "summary": "Listed tools with their canary state", "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at anyroute.tech yet; every route answers 404 while it is off. See /docs/#paid-tools. Public. Each listing has a daily paid probe with a known answer; three failures in a row delist it. include_delisted=true also returns delisted listings.", "security": [], "parameters": [ { "name": "include_delisted", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Listings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ToolListing" } }, "call": { "type": "string" }, "status": { "type": "object" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tools/search": { "get": { "tags": [ "Paid tools" ], "operationId": "searchPaidTools", "summary": "Search listings, facilitator sellers and the public catalog", "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at anyroute.tech yet; every route answers 404 while it is off. See /docs/#paid-tools. Public. The public catalog (TOOLS_PUBLIC_CATALOG_URL) is fetched through the egress guard and cached; facilitator sellers carry no canary.", "security": [], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "public", "in": "query", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ToolListing" } }, "public_catalog": { "type": "object" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tools/calls": { "get": { "tags": [ "Paid tools" ], "operationId": "listPaidToolCalls", "summary": "This key's paid tool calls", "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at anyroute.tech yet; every route answers 404 while it is off. See /docs/#paid-tools. The 50 newest calls of the calling key, with status (paying, ok, failed, released, charged_after_failure) and receipts.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Calls", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tools/calls/{id}": { "get": { "tags": [ "Paid tools" ], "operationId": "getPaidToolCall", "summary": "One paid tool call of this key", "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at anyroute.tech yet; every route answers 404 while it is off. See /docs/#paid-tools.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tc_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "The call" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tools/listings": { "post": { "tags": [ "Paid tools" ], "operationId": "createToolListing", "summary": "List an x402 tool with a known-answer canary", "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at anyroute.tech yet; every route answers 404 while it is off. See /docs/#paid-tools. Owner or admin key. The router asks the address unpaid: it must answer 402 with an offer this router can pay. The listing records that offer's payTo and price, and calls are refused if the payTo later changes. skill_id makes it the paid invocation of a Skills Hub skill the account published. 20 listings per account per hour.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolListingRequest" } } } }, "responses": { "201": { "description": "Listed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ToolListing" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "tool_already_listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "tool_not_payable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/tools/listings/{id}": { "delete": { "tags": [ "Paid tools" ], "operationId": "removeToolListing", "summary": "Remove a listing", "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at anyroute.tech yet; every route answers 404 while it is off. See /docs/#paid-tools. The listing account only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tl_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "Removed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tools/{id}": { "get": { "tags": [ "Paid tools" ], "operationId": "getToolListing", "summary": "One listing and its last ten canary runs", "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at anyroute.tech yet; every route answers 404 while it is off. See /docs/#paid-tools.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tl_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "The listing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ToolListing" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/{key_hash}/identity": { "get": { "operationId": "agentIdentitySettings", "tags": [ "Agent identity" ], "summary": "Read identity and reputation choices", "description": "Either AGENT_IDENTITY_ENABLED or PAID_FEEDBACK_ENABLED must be on; otherwise 404. Owner or administrator key of the same account; session keys are refused. Returns identity_opt_out (default true only when the key's rulebook allows only the unlinkable lane), reputation_opt_in (default false) and the ERC-8004 registration progress.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Choices and registration", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "setAgentIdentitySettings", "tags": [ "Agent identity" ], "summary": "Opt out of identity or in to paid reputation", "description": "Either flag must be on; otherwise 404. Owner or administrator key of the same account; session keys are refused. Opting out stops the registration file and every identity link the router publishes; a transaction already on chain stays there.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "identity_opt_out": { "type": "boolean" }, "reputation_opt_in": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated choices", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/{key_hash}/identity/register": { "post": { "operationId": "registerAgentIdentity", "tags": [ "Agent identity" ], "summary": "Prepare or queue an ERC-8004 registration", "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Owner or administrator key of the same account; session keys are refused. Needs a published profile and no opt-out. Owner mode returns register(agentURI, metadata) calldata for the canonical identity registry on Robinhood Chain, which the owner's wallet sends; registrar mode queues it for the isolated agent-identity worker. The router never sends the owner's transaction.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Calldata (owner mode) or queued (registrar mode)", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ApiError" }, "503": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/agents/{key_hash}/identity/confirm": { "post": { "operationId": "confirmAgentIdentity", "tags": [ "Agent identity" ], "summary": "Confirm the owner's registration transaction", "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Owner or administrator key of the same account; session keys are refused. Reads the transaction receipt and keeps the agent id from the identity registry's Registered event when its agentURI is this key's registration file. 409 while unconfirmed; 422 when it registered something else.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "tx_hash" ], "properties": { "tx_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } }, "responses": { "200": { "description": "Registered", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ApiError" }, "422": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/agents/{key_hash}/track-record": { "post": { "operationId": "issueAgentTrackRecord", "tags": [ "Agent identity" ], "summary": "Issue a portable track record", "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Also needs TLOG_ENABLED. Owner or administrator key of the same account; session keys are refused. A seven-day certificate signed with the receipt key: count of this key's anchored receipts, total spend, refund rate, dispute rate of agreements its wallet is party to, and a Merkle root over those receipts' anchor leaves. No counterparty or amount per counterparty. Returns the ERC-8004 validation entry it is the payload of. publish:true shows it on the card. Shares the five-per-minute certificate limit.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "publish": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Certificate, validation entry and proof URL", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ApiError" }, "422": { "$ref": "#/components/responses/ApiError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/agents/identity/{id}/registration.json": { "get": { "operationId": "agentRegistrationFile", "tags": [ "Agent identity" ], "summary": "Read an ERC-8004 registration file", "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. type https://eips.ethereum.org/EIPS/eip-8004#registration-v1, name, description, services (web, anyroute-card, the agent endpoint, anyroute-reputation when opted in, anyroute-receipt-keys), active, registrations and supportedTrust. 404 when the key opted out.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" } } ], "responses": { "200": { "description": "Registration file", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/track-records/verify": { "post": { "operationId": "verifyAgentTrackRecord", "tags": [ "Agent identity" ], "summary": "Check a track-record certificate", "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. Checks the signature against the published receipt keys, the seven-day window and internal consistency; not the router's underlying observations.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "{valid, notice}", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/track-records/{id}": { "get": { "operationId": "agentTrackRecord", "tags": [ "Agent identity" ], "summary": "Read a track record and its ERC-8004 validation entry", "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. The requestURI of the validation entry. validation carries request_hash (keccak256 of the canonical payload JSON), response 100, response_hash (keccak256 of the canonical signed certificate), tag anyroute-track-record, and calldata only when a validation registry, a validator and the agent's ERC-8004 id are all known. No validation registry exists on Robinhood Chain yet.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tr_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "Certificate, validity and validation entry", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/track-records/{id}/proof": { "get": { "operationId": "agentTrackRecordProof", "tags": [ "Agent identity" ], "summary": "Prove one counted receipt", "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. The leaf at index (ascending order), its path to the certificate's Merkle root, and its path to the hourly anchor root. 410 when the router no longer holds every counted receipt.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tr_[0-9a-f]{24}$" } }, { "name": "index", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Leaf, proof, root and anchor proof", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/ApiError" } } } }, "/api/v1/agents/{slug}/reputation": { "get": { "operationId": "agentReputation", "tags": [ "Agent identity" ], "summary": "Read paid-feedback reputation", "description": "PAID_FEEDBACK_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. opted_in false until the owner opts in. Otherwise the weighted score (0 to 100), feedback_count, weight_usd, by_kind, half_life_days and up to 20 recent entries with a payment band and day. Weight is the amount paid, halving every PAID_FEEDBACK_HALF_LIFE_DAYS after the payment. Reviewers are never shown.", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" } } ], "responses": { "200": { "description": "Reputation", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/{slug}/feedback": { "post": { "operationId": "giveAgentFeedback", "tags": [ "Agent identity" ], "summary": "Give feedback backed by a paid receipt", "description": "PAID_FEEDBACK_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Any key of the paying account. No receipt, no feedback: the router's record of receipt_id must name the caller's account as payer and this agent as payee or agent served (model.call: a call answered by a network host the agent's account operates; agreement.release: a released milestone paid to the agent's wallet; other kinds may register). Refused: unknown or unpaid receipts, unlinkable or blind payments, another payer's receipt, a receipt already used, and any account that controls the agent. Thirty per minute per account. For an agent with an ERC-8004 identity, erc8004 carries optional giveFeedback calldata for the reviewer's own wallet.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "receipt_id", "score" ], "properties": { "receipt_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "receipt_kind": { "type": "string", "description": "model.call, agreement.release or another registered kind; omitted means every known kind is tried." }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "tag1": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9 ._:-]+$" }, "tag2": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9 ._:-]+$" } } } } } }, "responses": { "201": { "description": "Recorded entry", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ApiError" }, "422": { "$ref": "#/components/responses/ApiError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/agents/{slug}/feedback/{id}": { "delete": { "operationId": "withdrawAgentFeedback", "tags": [ "Agent identity" ], "summary": "Withdraw one's own feedback", "description": "PAID_FEEDBACK_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Only a key of the reviewing account.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{24}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fb_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "Withdrawn", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/feedback/{id}": { "get": { "operationId": "agentFeedbackEntry", "tags": [ "Agent identity" ], "summary": "Read one public feedback entry", "description": "PAID_FEEDBACK_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public; the feedbackURI of the optional ERC-8004 entry. Score, tags, receipt kind, payment band and day; never the reviewer, the receipt id or the exact amount.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fb_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "Entry", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/commerce/stats": { "get": { "tags": [ "Status" ], "operationId": "commerceStats", "summary": "Read the commerce ledger", "description": "Present only with COMMERCE_STATS_ENABLED (default false; not switched on at anyroute.tech yet). Public, read-only snapshots cached at most 60 seconds; HTTP freshness is limited to the remaining snapshot lifetime. Settlements per receipt kind (model.call for x402 model calls; tool.call, facilitator.settle and job.release once their features report settlements) over 24 hours, 7 days and 30 days. Every block carries gross and filtered figures side by side, plus how many settlements each rule excluded: unanchored (a receipt not in a root confirmed on ReceiptAnchor), same_owner (same wallet, same owner key, or both operator wallets), round_trip (value back from payee to payer within 24 hours), funding_link (USDG funding within COMMERCE_FUNDING_HOPS transfers; only when filters.funding.available). Amounts are decimal strings in USDG base units. Counts, sums and medians only: no payer, payee, transaction or single settlement, and no split by privacy lane. Methodology: /docs/#commerce-stats; integrations/dune/commerce.sql recomputes the on-chain part.", "security": [], "responses": { "200": { "description": "Commerce ledger snapshot", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=, must-revalidate" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommerceStats" } } } } } }, "404": { "$ref": "#/components/responses/NotFound", "description": "The commerce ledger is disabled" }, "503": { "description": "A source could not be read; no stale snapshot is served", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/escrow/deposits": { "get": { "tags": [ "Credits" ], "summary": "Read deposit progress and approximate finality time", "description": "B123: active bearer key required. Account credit progress allows owner/admin/member/viewer roles and excludes session keys; escrow deposits are scoped to the wallet behind the key. Nullable expected_final_at is an estimate, never proof of finality. No-store.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Deposit stages with an optional timing estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "expected_final_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Approximate ISO finality estimate from live block progress; null when unavailable. Not a deadline." } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/credits/deposits": { "get": { "tags": [ "Credits" ], "summary": "Read deposit progress and approximate finality time", "description": "B123: active bearer key required. Account credit progress allows owner/admin/member/viewer roles and excludes session keys; escrow deposits are scoped to the wallet behind the key. Nullable expected_final_at is an estimate, never proof of finality. No-store.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Deposit stages with an optional timing estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "expected_final_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Approximate ISO finality estimate from live block progress; null when unavailable. Not a deadline." } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/account/runway": { "get": { "tags": [ "Keys" ], "summary": "Estimate balance runway", "description": "Same active-key authentication and visibility as credits: account-scoped keys see the account; sessions see remaining budget and their own charges. Inference-only keys are forbidden. Settled balance divided by seven-day charged usage/tool spend per day, rounded down; null without spending. Refunds, token purchases and holds are excluded.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance_usd", "spend_7d_usd", "per_day_usd", "days_left" ], "properties": { "balance_usd": { "type": "number" }, "spend_7d_usd": { "type": "number" }, "per_day_usd": { "type": "number" }, "days_left": { "type": [ "integer", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getAccountRunway" } }, "/api/v1/account/low-balance": { "get": { "tags": [ "Keys" ], "summary": "Read balance alert setting", "description": "Owner keys only; no session or inference-only keys. enabled reports LOW_BALANCE_ALERTS_ENABLED (default false).", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "low_balance_usd", "enabled" ], "properties": { "low_balance_usd": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000 }, "enabled": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getLowBalanceSetting" }, "patch": { "tags": [ "Keys" ], "summary": "Set balance alert threshold", "description": "Owner keys only; no session or inference-only keys. 403 while LOW_BALANCE_ALERTS_ENABLED is false. Null clears the setting. A changed threshold starts a new crossing check; an unchanged threshold preserves the claim. Worker checks every five minutes, records an inbox low_balance item, and attempts linked Telegram delivery once per crossing. Re-arms strictly above the threshold.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success; Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "low_balance_usd", "enabled" ], "properties": { "low_balance_usd": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000 }, "enabled": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "low_balance_usd" ], "properties": { "low_balance_usd": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000 } } } } } }, "operationId": "setLowBalanceSetting" } }, "/api/v1/models/new.atom": { "get": { "summary": "C131: new models feed", "description": "Visible models first observed in the catalogue in the last 30 days. Baseline arrivals are unknown and excluded. Empty when MODEL_ARRIVALS_ENABLED is off (default). Public, cached for 30 seconds.", "security": [], "responses": { "200": { "description": "Atom feed", "headers": { "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } }, "/api/v1/account/reliability": { "get": { "operationId": "accountReliability", "summary": "Read your recorded call reliability", "description": "E155: read-only rolling report, 1–7 days. Same auth and account/key/session visibility as Activity, with its agent team boundary. No new flag. Success covers only non-cancelled, non-error generation records; pre-generation failures and general lane/balance refusals are missing. Fallback calls are receipt route records marked fallback (including retries/model changes); fallback_rate divides by route_recorded_calls, not all calls. Missing route records are unknown. Percentages round to one decimal, null for empty denominators. First-token times cover non-cache streams; total latency uses generation_time_ms. Null/negative timing excluded, fields omitted without samples. Median/p95 use linear interpolation. Refusals count denied inference decisions, not unique requests; categories overlap, approvals excluded. Lane means lane_not_allowed; budget means per-request/hour/day/week caps or spending breaker; rulebook means other codes. Refusal counts are zero with agent policies off. Existing records only; no response persistence. See /docs/#reliability-report.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 7, "default": 7 } } ], "responses": { "200": { "description": "Reliability counts and available timing by model. Cache-Control: no-store.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "scope", "days", "from", "to", "totals", "models" ], "properties": { "scope": { "type": "string", "enum": [ "account", "key" ] }, "days": { "type": "integer" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "totals": { "type": "object", "required": [ "calls", "succeeded", "success_rate", "route_recorded_calls", "fallback_calls", "fallback_rate", "refusals" ], "properties": { "calls": { "type": "string", "pattern": "^[0-9]+$" }, "succeeded": { "type": "string", "pattern": "^[0-9]+$" }, "route_recorded_calls": { "type": "string", "pattern": "^[0-9]+$" }, "fallback_calls": { "type": "string", "pattern": "^[0-9]+$" }, "success_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "fallback_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "time_to_first_token_ms": { "type": "object", "required": [ "samples", "median", "p95" ], "properties": { "samples": { "type": "string", "pattern": "^[0-9]+$" }, "median": { "type": "number", "minimum": 0 }, "p95": { "type": "number", "minimum": 0 } } }, "total_latency_ms": { "type": "object", "required": [ "samples", "median", "p95" ], "properties": { "samples": { "type": "string", "pattern": "^[0-9]+$" }, "median": { "type": "number", "minimum": 0 }, "p95": { "type": "number", "minimum": 0 } } }, "refusals": { "type": "object", "required": [ "decisions", "lane", "budget", "rulebook" ], "properties": { "decisions": { "type": "string", "pattern": "^[0-9]+$" }, "lane": { "type": "string", "pattern": "^[0-9]+$" }, "budget": { "type": "string", "pattern": "^[0-9]+$" }, "rulebook": { "type": "string", "pattern": "^[0-9]+$" } } } } }, "models": { "type": "array", "items": { "type": "object", "required": [ "model", "calls", "succeeded", "success_rate", "route_recorded_calls", "fallback_calls", "fallback_rate", "refusals" ], "properties": { "model": { "type": [ "string", "null" ] }, "calls": { "type": "string", "pattern": "^[0-9]+$" }, "succeeded": { "type": "string", "pattern": "^[0-9]+$" }, "route_recorded_calls": { "type": "string", "pattern": "^[0-9]+$" }, "fallback_calls": { "type": "string", "pattern": "^[0-9]+$" }, "success_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "fallback_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "time_to_first_token_ms": { "type": "object", "required": [ "samples", "median", "p95" ], "properties": { "samples": { "type": "string", "pattern": "^[0-9]+$" }, "median": { "type": "number", "minimum": 0 }, "p95": { "type": "number", "minimum": 0 } } }, "total_latency_ms": { "type": "object", "required": [ "samples", "median", "p95" ], "properties": { "samples": { "type": "string", "pattern": "^[0-9]+$" }, "median": { "type": "number", "minimum": 0 }, "p95": { "type": "number", "minimum": 0 } } }, "refusals": { "type": "object", "required": [ "decisions", "lane", "budget", "rulebook" ], "properties": { "decisions": { "type": "string", "pattern": "^[0-9]+$" }, "lane": { "type": "string", "pattern": "^[0-9]+$" }, "budget": { "type": "string", "pattern": "^[0-9]+$" }, "rulebook": { "type": "string", "pattern": "^[0-9]+$" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/insights": { "get": { "operationId": "projectSpendInsights", "summary": "Read spend insights", "description": "C134: requires SPEND_INSIGHTS_ENABLED (default false). Existing account/key access rules apply. Project filters call charges and generation-linked refunds; unlinked refunds have no project. Optional projects breakdown uses the existing spend row fields: id, cost_usd, charged_usd, refunded_usd and calls, with null id for no project; omitted when there are no tagged records. Signed receipts and Statements are unchanged.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "project", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]{1,48}$" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "bucket", "in": "query", "schema": { "type": "string", "enum": [ "day", "week" ] } } ], "responses": { "200": { "description": "UTC spend report with optional project breakdown." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/{key_hash}/quiet-alert": { "get": { "operationId": "getQuietAgentAlert", "summary": "Read quiet-agent alert settings", "description": "D141. Requires QUIET_AGENT_ALERTS_ENABLED and AGENT_POLICY_ENABLED. Management keys or owning team owner/admin keys only; inference and session keys refused. Off returns 404. Settings are outside the rulebook. One inbox notice per quiet period; Telegram is attempted once if linked. Charged calls and Guard decisions re-arm; stopped keys are excluded. Checks run every five minutes.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Quiet alert setting", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "key_hash", "hours" ], "properties": { "key_hash": { "type": "string" }, "hours": { "type": [ "integer", "null" ], "enum": [ null, 1, 3, 6, 12, 24, 72 ] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Agent rulebook" ] }, "put": { "operationId": "putQuietAgentAlert", "summary": "Set a quiet-agent alert window", "description": "D141. Requires QUIET_AGENT_ALERTS_ENABLED and AGENT_POLICY_ENABLED. Management keys or owning team owner/admin keys only; inference and session keys refused. Off returns 404. Settings are outside the rulebook. One inbox notice per quiet period; Telegram is attempted once if linked. Charged calls and Guard decisions re-arm; stopped keys are excluded. Checks run every five minutes.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Quiet alert setting", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "key_hash", "hours" ], "properties": { "key_hash": { "type": "string" }, "hours": { "type": [ "integer", "null" ], "enum": [ null, 1, 3, 6, 12, 24, 72 ] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "hours" ], "properties": { "hours": { "type": [ "integer", "null" ], "enum": [ null, 1, 3, 6, 12, 24, 72 ] } } } } } }, "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Agent rulebook" ] } }, "/api/v1/account/security-alerts": { "get": { "operationId": "getSecurityAlerts", "summary": "Read security alerts preference", "description": "D138: SECURITY_ALERTS_ENABLED defaults to false (404 while off). Active account management Bearer key required; session keys and team administrators refused. Preference defaults on. Responses use no-store.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Saved preference", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "patchSecurityAlerts", "summary": "Save security alerts preference", "description": "D138: SECURITY_ALERTS_ENABLED defaults to false (404 while off). Active account management Bearer key required; session keys and team administrators refused. Preference defaults on. Responses use no-store.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Saved preference", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } } } } } }, "/api/v1/messages": { "post": { "operationId": "createMessage", "summary": "Create a message", "description": "D145: also served under /v1. Idempotency-Key is optional and requires an API key with the usual inference role. Messages accepts x-api-key or Authorization: Bearer. Matching retries return the kept final JSON and receipt headers without another charge. Streams return 409 with receipt_id when complete. Results are encrypted and expire 24 hours from the first request. See /docs/#idempotency.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "D145: opt-in API-key retry protection, scoped to account + API key + retry key for 24 hours from the first request. Canonical body and endpoint must match. Reply encrypted at rest. Headerless behavior is unchanged. See /docs/#idempotency.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]{1,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Inference reply or original kept result.", "headers": { "Idempotent-Replay": { "description": "true for a kept-result replay.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "idempotency_in_progress or idempotency_result_not_kept, with original receipt_id when available." }, "422": { "description": "idempotency_key_reused: different body or endpoint." }, "503": { "description": "idempotency_unavailable: no new protected call runs." } } } }, "/api/v1/completions": { "post": { "operationId": "createCompletion", "summary": "Create a text completion", "description": "D145: also served under /v1. Idempotency-Key is optional and requires an API key with the usual inference role. Messages accepts x-api-key or Authorization: Bearer. Matching retries return the kept final JSON and receipt headers without another charge. Streams return 409 with receipt_id when complete. Results are encrypted and expire 24 hours from the first request. See /docs/#idempotency.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "D145: opt-in API-key retry protection, scoped to account + API key + retry key for 24 hours from the first request. Canonical body and endpoint must match. Reply encrypted at rest. Headerless behavior is unchanged. See /docs/#idempotency.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]{1,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Inference reply or original kept result.", "headers": { "Idempotent-Replay": { "description": "true for a kept-result replay.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "idempotency_in_progress or idempotency_result_not_kept, with original receipt_id when available." }, "422": { "description": "idempotency_key_reused: different body or endpoint." }, "503": { "description": "idempotency_unavailable: no new protected call runs." } } } }, "/api/v1/schedules": { "get": { "operationId": "listSchedules", "tags": [ "Scheduled prompts" ], "summary": "List saved prompts", "description": "D136: SCHEDULED_PROMPTS_ENABLED defaults to false. Requires an active owner or management Bearer key; inference, session and team administrator keys are refused. Paying keys must belong to the owner and its team scope.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledPrompt" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createSchedule", "tags": [ "Scheduled prompts" ], "summary": "Save a scheduled prompt", "description": "D136: SCHEDULED_PROMPTS_ENABLED defaults to false. Requires an active owner or management Bearer key; inference, session and team administrator keys are refused. Paying keys must belong to the owner and its team scope.", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScheduledPrompt" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledPromptInput" } } } } } }, "/api/v1/schedules/{id}": { "get": { "operationId": "readSchedule", "tags": [ "Scheduled prompts" ], "summary": "Read a saved prompt", "description": "D136: SCHEDULED_PROMPTS_ENABLED defaults to false. Requires an active owner or management Bearer key; inference, session and team administrator keys are refused. Paying keys must belong to the owner and its team scope.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScheduledPrompt" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "updateSchedule", "tags": [ "Scheduled prompts" ], "summary": "Edit or pause a scheduled prompt", "description": "D136: SCHEDULED_PROMPTS_ENABLED defaults to false. Requires an active owner or management Bearer key; inference, session and team administrator keys are refused. Paying keys must belong to the owner and its team scope.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScheduledPrompt" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledPromptPatch" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "operationId": "deleteSchedule", "tags": [ "Scheduled prompts" ], "summary": "Delete a prompt and its saved runs", "description": "D136: SCHEDULED_PROMPTS_ENABLED defaults to false. Requires an active owner or management Bearer key; inference, session and team administrator keys are refused. Paying keys must belong to the owner and its team scope.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schedule and all saved runs deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/schedules/{id}/runs": { "get": { "operationId": "listScheduleRuns", "tags": [ "Scheduled prompts" ], "summary": "Read the last ten saved results", "description": "D136: SCHEDULED_PROMPTS_ENABLED defaults to false. Requires an active owner or management Bearer key; inference, session and team administrator keys are refused. Paying keys must belong to the owner and its team scope.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledPromptRun" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/schedules/{id}/run-now": { "post": { "operationId": "runScheduleNow", "tags": [ "Scheduled prompts" ], "summary": "Run a saved prompt now", "description": "D136: SCHEDULED_PROMPTS_ENABLED defaults to false. Requires an active owner or management Bearer key; inference, session and team administrator keys are refused. Paying keys must belong to the owner and its team scope.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScheduledPromptRun" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Agent-Approval", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Existing single-use approval, checked against the ordinary inference intent and estimated cost." } ] } }, "/api/v1/projects": { "get": { "tags": [ "Projects" ], "summary": "List account projects with charged spend and budgets for the current UTC month", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Project monthly accounting", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectBudget" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Requires an active account management owner key; session and team-scoped keys cannot manage these account-wide limits. Budget amounts use USD and calendar months UTC." } }, "/api/v1/projects/{name}/budget": { "get": { "tags": [ "Projects" ], "summary": "Read a project budget and current UTC month charged spend", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Project monthly accounting", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectBudget" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]{1,48}$" } } ], "description": "Requires an active account management owner key; session and team-scoped keys cannot manage these account-wide limits. Budget amounts use USD and calendar months UTC." }, "put": { "tags": [ "Projects" ], "summary": "Set a recurring monthly project budget", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Project monthly accounting", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectBudget" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "budget_usd" ], "properties": { "budget_usd": { "type": "number", "minimum": 0, "maximum": 1000000 } } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]{1,48}$" } } ], "description": "Requires an active account management owner key; session and team-scoped keys cannot manage these account-wide limits. Budget amounts use USD and calendar months UTC." }, "delete": { "tags": [ "Projects" ], "summary": "Remove a project budget; preserve charged history and notices", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Project monthly accounting", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectBudget" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]{1,48}$" } } ], "description": "Requires an active account management owner key; session and team-scoped keys cannot manage these account-wide limits. Budget amounts use USD and calendar months UTC." } }, "/api/v1/agents/{key_hash}/policy/versions": { "get": { "x-card": "D144", "tags": [ "Agent rulebook" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "agentPolicyVersions", "summary": "Read saved rulebook versions", "description": "Requires the same Bearer owner/admin, management, account and team scope as PUT policy. Session and inference-only keys are refused. AGENT_POLICY_ENABLED defaults false; off returns 404. Cache-Control: no-store. Returns at most 50 retained revisions newest first by id, including repeated saves. Diffs use the shared plain-English sentence formatter and compare consecutive versions. The migration only retains the current rules and their last-update metadata; lost earlier rules are not recovered. Full readable rulebooks and saving key hashes remain until operator deletion, including after removing the current rulebook.", "responses": { "200": { "description": "Saved versions", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "id", "key_hash", "sha256", "spec", "saved_at", "saved_by", "source", "diff" ], "properties": { "id": { "type": "integer" }, "key_hash": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "spec": { "$ref": "#/components/schemas/AgentPolicy" }, "saved_at": { "type": "string", "format": "date-time" }, "saved_by": { "type": "string", "description": "Saving principal key hash; migration copies use the current row’s last updater." }, "source": { "type": "string", "enum": [ "save", "approve_and_allow", "restore", "playbook" ] }, "diff": { "type": "object", "required": [ "added", "removed" ], "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/{key_hash}/policy/restore": { "post": { "x-card": "D144", "tags": [ "Agent rulebook" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "restoreAgentPolicy", "summary": "Restore saved rules as a new revision", "description": "Requires the same Bearer owner/admin, management, account and team scope as PUT policy. Session and inference-only keys are refused. AGENT_POLICY_ENABLED defaults false; off returns 404. Cache-Control: no-store. The SHA-256 must belong to this key’s history. Validates the saved spec and digest, saves a new restore revision and appends policy_set to the existing hash chain in one account-locked transaction. Keeps Stop state and inherited rules. Following playbook keys are refused until they stop following.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "sha256" ], "properties": { "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Rules restored as a normal save", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "key_hash", "policy", "sha256", "version" ], "properties": { "key_hash": { "type": "string" }, "policy": { "$ref": "#/components/schemas/AgentPolicy" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "version": { "type": "integer", "const": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "This key follows a playbook, or the saved rules do not match their digest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/account/notifications": { "get": { "summary": "Read account notifications", "description": "E146. Active management owner Bearer key; session and team keys excluded. No-store. Quiet delivery worker NOTIFICATION_QUIET_HOURS_ENABLED defaults false. Existing feature gates apply. Weekly Telegram writes existing link opt-ins; security switches share the existing preference. Defaults preserve current channels.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Account notification preferences", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "channels", "quiet_hours" ], "properties": { "channels": { "type": "object", "additionalProperties": false, "required": [ "approvals", "agent_alerts", "deposits", "low_balance", "weekly_summary", "security_alerts", "quiet_agents", "price_notices", "project_budgets", "approval_reminders", "scheduled_results", "status_incidents", "model_watch" ], "properties": { "approvals": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "agent_alerts": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "deposits": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "low_balance": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "weekly_summary": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "security_alerts": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "quiet_agents": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "price_notices": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "project_budgets": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "approval_reminders": { "type": "object", "description": "G164: Approval reminders; both channels default on and quiet hours do not delay Telegram reminders.", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": true }, "telegram": { "type": "boolean", "default": true } } }, "scheduled_results": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "status_incidents": { "type": "object", "description": "H169: Service incidents; opt-in on both channels. Requires STATUS_INCIDENT_NOTICES_ENABLED for processing. Quiet hours hold Telegram notices.", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": false }, "telegram": { "type": "boolean", "default": false } } }, "model_watch": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": true }, "telegram": { "type": "boolean", "default": true } } } } }, "quiet_hours": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "from_utc", "to_utc" ], "properties": { "from_utc": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "to_utc": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" } } } ] }, "telegram_linked": { "type": "boolean" }, "quiet_hours_available": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Link Telegram before enabling weekly summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "readAccountNotifications" }, "put": { "summary": "Save account notifications", "description": "E146. Active management owner Bearer key; session and team keys excluded. No-store. Quiet delivery worker NOTIFICATION_QUIET_HOURS_ENABLED defaults false. Existing feature gates apply. Weekly Telegram writes existing link opt-ins; security switches share the existing preference. Defaults preserve current channels.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Account notification preferences", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "channels", "quiet_hours" ], "properties": { "channels": { "type": "object", "additionalProperties": false, "required": [ "approvals", "agent_alerts", "deposits", "low_balance", "weekly_summary", "security_alerts", "quiet_agents", "price_notices", "project_budgets", "approval_reminders", "scheduled_results", "status_incidents", "model_watch" ], "properties": { "approvals": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "agent_alerts": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "deposits": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "low_balance": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "weekly_summary": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "security_alerts": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "quiet_agents": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "price_notices": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "project_budgets": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "approval_reminders": { "type": "object", "description": "G164: Approval reminders; both channels default on and quiet hours do not delay Telegram reminders.", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": true }, "telegram": { "type": "boolean", "default": true } } }, "scheduled_results": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "status_incidents": { "type": "object", "description": "H169: Service incidents; opt-in on both channels. Requires STATUS_INCIDENT_NOTICES_ENABLED for processing. Quiet hours hold Telegram notices.", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": false }, "telegram": { "type": "boolean", "default": false } } }, "model_watch": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": true }, "telegram": { "type": "boolean", "default": true } } } } }, "quiet_hours": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "from_utc", "to_utc" ], "properties": { "from_utc": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "to_utc": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" } } } ] }, "telegram_linked": { "type": "boolean" }, "quiet_hours_available": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Link Telegram before enabling weekly summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "channels", "quiet_hours" ], "properties": { "channels": { "type": "object", "additionalProperties": false, "required": [ "approvals", "agent_alerts", "deposits", "low_balance", "weekly_summary", "security_alerts", "quiet_agents", "price_notices", "project_budgets", "approval_reminders", "scheduled_results", "status_incidents", "model_watch" ], "properties": { "approvals": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "agent_alerts": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "deposits": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "low_balance": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "weekly_summary": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "security_alerts": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "quiet_agents": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "price_notices": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "project_budgets": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "approval_reminders": { "type": "object", "description": "G164: Approval reminders; both channels default on and quiet hours do not delay Telegram reminders.", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": true }, "telegram": { "type": "boolean", "default": true } } }, "scheduled_results": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "status_incidents": { "type": "object", "description": "H169: Service incidents; opt-in on both channels. Requires STATUS_INCIDENT_NOTICES_ENABLED for processing. Quiet hours hold Telegram notices.", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": false }, "telegram": { "type": "boolean", "default": false } } }, "model_watch": { "type": "object", "additionalProperties": false, "required": [ "inbox", "telegram" ], "properties": { "inbox": { "type": "boolean", "default": true }, "telegram": { "type": "boolean", "default": true } } } } }, "quiet_hours": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "from_utc", "to_utc" ], "properties": { "from_utc": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "to_utc": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" } } } ] } } } } } }, "operationId": "saveAccountNotifications" } }, "/api/v1/agents/{key_hash}/approvers": { "get": { "tags": [ "Agent rulebook" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "key_hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approver settings and eligible teammates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "owners", "owners_and_admins", "specific_members" ] }, "member_ids": { "type": "array", "maxItems": 100, "uniqueItems": true, "default": [], "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "configured": { "type": "boolean" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } } } } }, "required": [ "mode", "member_ids", "configured", "members" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "E153. Requires account management or team owner/admin key outside sessions. AGENT_TEAM_APPROVERS_ENABLED defaults false; off or AGENT_POLICY_ENABLED off returns 404. With the flag on, unset settings mean owners only. Owners always approve. Selected principal IDs survive member sign-in rotation; legacy members use key hashes. Member requests cannot be approved by their own key or another key for the same principal. Approve and allow retains owner/admin permission and must also pass approval authority.", "operationId": "getAgentApprovers" }, "put": { "tags": [ "Agent rulebook" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "key_hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approver settings and eligible teammates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "owners", "owners_and_admins", "specific_members" ] }, "member_ids": { "type": "array", "maxItems": 100, "uniqueItems": true, "default": [], "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "configured": { "type": "boolean" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } } } } }, "required": [ "mode", "member_ids", "configured", "members" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "E153. Requires account management or team owner/admin key outside sessions. AGENT_TEAM_APPROVERS_ENABLED defaults false; off or AGENT_POLICY_ENABLED off returns 404. With the flag on, unset settings mean owners only. Owners always approve. Selected principal IDs survive member sign-in rotation; legacy members use key hashes. Member requests cannot be approved by their own key or another key for the same principal. Approve and allow retains owner/admin permission and must also pass approval authority.", "operationId": "putAgentApprovers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "owners", "owners_and_admins", "specific_members" ] }, "member_ids": { "type": "array", "maxItems": 100, "uniqueItems": true, "default": [], "items": { "type": "string", "minLength": 1, "maxLength": 128 } } } } } } } } }, "/api/v1/account/wallets": { "get": { "tags": [ "Linked wallets" ], "summary": "List linked secondary wallets", "description": "E154. Requires an account owner management API key. Responses are not cached.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "wallet", "linked_at" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "linked_at": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Wallet has its own account or is already linked; accounts cannot be merged" } } }, "post": { "tags": [ "Linked wallets" ], "summary": "Verify a one-time secondary wallet signature", "description": "E154. Requires an account owner management API key. Responses are not cached.", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "wallet", "linked_at" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "linked_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Wallet has its own account or is already linked; accounts cannot be merged" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "nonce", "signature" ], "properties": { "nonce": { "type": "string", "pattern": "^[0-9a-f]{48}$" }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" } } } } } } } }, "/api/v1/account/wallets/challenge": { "post": { "tags": [ "Linked wallets" ], "summary": "Request a five-minute wallet link message", "description": "E154. Requires an account owner management API key. Responses are not cached.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "nonce", "message", "chain_id", "expires_at" ], "properties": { "nonce": { "type": "string", "pattern": "^[0-9a-f]{48}$" }, "message": { "type": "string", "description": "Exact personal-sign message binding account, action, origin, chain ID, secondary wallet, nonce and expiry." }, "chain_id": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Wallet has its own account or is already linked; accounts cannot be merged" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "address" ], "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } } } } } } }, "/api/v1/account/wallets/{address}": { "delete": { "tags": [ "Linked wallets" ], "summary": "Unlink a secondary wallet after confirmation", "description": "E154. Requires an account owner management API key. Responses are not cached.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "unlinked": { "type": "boolean", "const": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Wallet has its own account or is already linked; accounts cannot be merged" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "confirm" ], "properties": { "confirm": { "type": "boolean", "const": true } } } } } }, "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ] } }, "/api/v1/keys/{hash}/rotate": { "post": { "tags": [ "Keys" ], "summary": "Rotate an account-backed key without downtime", "description": "G158. Same key-edit owner/admin authentication as PATCH; management keys can rotate other keys in their account, team owner/admin keys only themselves. Restricted callers, sessions, inactive keys, already replaced keys and chain-funded or deposit-first keys are refused. Copies all settings, policy revisions, approvers and alert rules; usage stays with the old key. Both keys share the account balance. Old expiry is capped by grace and cannot be extended past it. Existing security_alerts preferences and delivery apply. No new config flag. Secret returned once; Cache-Control: no-store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "grace" ], "properties": { "grace": { "type": "string", "enum": [ "1h", "24h", "7d" ] } } } } } }, "responses": { "201": { "description": "Replacement key and one-time secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "writeOnly": true }, "data": { "type": "object", "description": "Existing key representation, with copied expiry and settings and zero usage." }, "rotation": { "type": "object", "required": [ "from", "to", "at", "grace_ends_at", "history_key_hash" ], "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "at": { "type": "string", "format": "date-time" }, "grace_ends_at": { "type": "string", "format": "date-time" }, "history_key_hash": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "description": "Chain funding could not be checked; key remains unchanged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/keys/{hash}/rotation": { "get": { "tags": [ "Keys" ], "summary": "Read key rotation links and dates", "description": "G158. Existing owner/admin/viewer key-read auth and account/team ownership. Read-only and inference-only callers refused. Returns data null until rotated. Cache-Control: no-store. history_key_hash links to the original rulebook history.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotation metadata or null", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "required": [ "from", "to", "at", "grace_ends_at", "history_key_hash" ], "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "at": { "type": "string", "format": "date-time" }, "grace_ends_at": { "type": "string", "format": "date-time" }, "history_key_hash": { "type": "string" } } }, { "type": "null" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/account/model-watch": { "get": { "summary": "List watched models", "description": "G159. Active account management owner key required; session, team and read-only keys refused. MODEL_WATCH_ENABLED defaults false. Cache-Control: no-store. Watches are capped at 20. PUT and DELETE are idempotent. DELETE clears saved notices and retains any unexpired one-hour cooldown.", "security": [ { "BearerAuth": [] } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "200": { "description": "Current account watches", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "limit" ], "properties": { "limit": { "type": "integer", "enum": [ 20 ] }, "data": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "model", "name", "watched_at" ], "properties": { "model": { "type": "string" }, "name": { "type": "string" }, "watched_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "operationId": "listModelWatches" }, "put": { "summary": "Watch a model", "description": "G159. Active account management owner key required; session, team and read-only keys refused. MODEL_WATCH_ENABLED defaults false. Cache-Control: no-store. Watches are capped at 20. PUT and DELETE are idempotent. DELETE clears saved notices and retains any unexpired one-hour cooldown.", "security": [ { "BearerAuth": [] } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "description": "Watch limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "200": { "description": "Current account watches", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "limit" ], "properties": { "limit": { "type": "integer", "enum": [ 20 ] }, "data": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "model", "name", "watched_at" ], "properties": { "model": { "type": "string" }, "name": { "type": "string" }, "watched_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 256 } } } } } }, "operationId": "addModelWatch" }, "delete": { "summary": "Unwatch a model", "description": "G159. Active account management owner key required; session, team and read-only keys refused. MODEL_WATCH_ENABLED defaults false. Cache-Control: no-store. Watches are capped at 20. PUT and DELETE are idempotent. DELETE clears saved notices and retains any unexpired one-hour cooldown.", "security": [ { "BearerAuth": [] } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "description": "Watch limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "200": { "description": "Current account watches", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "limit" ], "properties": { "limit": { "type": "integer", "enum": [ 20 ] }, "data": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "model", "name", "watched_at" ], "properties": { "model": { "type": "string" }, "name": { "type": "string" }, "watched_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 256 } } } } } }, "operationId": "removeModelWatch" } }, "/api/v1/agents/{key}/duplicate": { "post": { "tags": [ "Agents" ], "summary": "Duplicate an agent", "description": "H171. Requires AGENT_POLICY_ENABLED. Management key in the same account or owner/admin in the source team; no permission escalation. Read-only, inference-only and session callers are refused, as are session sources. Copies configuration and current rulebook as its first revision, detached from playbooks, with a Copied from note in the new event log. New key shares the account balance. Spend, history, approvals, disabled/Stop state, rotation links, browser sign-ins, principal bindings, Telegram links, profiles, attestation and spend-alert destinations are not copied. Existing security_alerts preferences and quiet-hour delivery apply. No new flag. Secret returned once with Cache-Control: no-store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Trimmed new name; omitted uses source name plus copy, shortened to 100 characters." } } } } } }, "responses": { "201": { "description": "Independent key created; secret is returned once.", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "key", "note" ], "properties": { "data": { "type": "object", "description": "Existing key details: hash, name, label, limits, zero usage, copied settings and fresh identity." }, "key": { "type": "string", "description": "One-time new API secret; never stored by the duplication interface." }, "note": { "type": "string", "description": "Copied from followed by the source name; also saved on the new event log." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/agents/{key_hash}/runway": { "get": { "operationId": "agentRunway", "summary": "Estimate how long an agent’s caps last", "description": "H170: Same auth and visibility as agent policy GET; read-only keys refused. Existing AGENT_POLICY_ENABLED defaults false; off returns 404. Own posted charges only, excluding sessions and open holds. Rulebook windows remain rolling; calendar key budgets reset in UTC. Gross charges ignore refunds. Daily pace uses elapsed local day; week/month/total use seven rolling days. Estimates hold the current effective cap constant and do not predict enforcement. No new storage, migration or flag. See /docs/#agent-runway.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Uncached runway estimate, including keys with no caps.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key_hash": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "time_zone": { "type": "string" }, "today_from": { "type": "string", "format": "date-time" }, "today_charged_usd": { "type": "number" }, "spend_7d_usd": { "type": "number" }, "estimate": { "type": "boolean", "const": true }, "limits": { "type": "array", "items": { "type": "object", "properties": { "source": { "enum": [ "rulebook", "key_budget" ] }, "period": { "enum": [ "request", "hour", "day", "week", "month", "total" ] }, "cap_usd": { "type": "number" }, "pace_per_day_usd": { "type": "number" }, "charged_usd": { "type": [ "number", "null" ] }, "remaining_usd": { "type": [ "number", "null" ] }, "estimated_days_left": { "type": [ "number", "null" ] }, "estimated_reaches_at": { "type": [ "string", "null" ], "format": "date-time" }, "resets_at": { "type": [ "string", "null" ], "format": "date-time" }, "reaches_before_reset": { "type": [ "boolean", "null" ] } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/stop-all": { "post": { "operationId": "stopAllAgents", "tags": [ "Agent rulebook" ], "summary": "Stop all agents", "description": "H172: Owner/admin/management Bearer key. Team keys act only within their own team and account; management keys act across the account. Read-only, inference-only and session keys refused. AGENT_POLICY_ENABLED defaults false; off returns 404. Only own rulebooks are changed, in one transaction through the existing per-agent Stop path. Counts reflect changes; repeats return zero. Existing active stops retain their duration; resume clears any stored stop.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Changed-agent count and plain confirmation", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "count", "message" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 160 }, "until": { "type": "string", "format": "date-time", "description": "Future absolute time within 30 days. Omit to stop until resumed." } } } } } } } }, "/api/v1/agents/resume-all": { "post": { "operationId": "resumeAllAgents", "tags": [ "Agent rulebook" ], "summary": "Resume all agents", "description": "H172: Owner/admin/management Bearer key. Team keys act only within their own team and account; management keys act across the account. Read-only, inference-only and session keys refused. AGENT_POLICY_ENABLED defaults false; off returns 404. Only own rulebooks are changed, in one transaction through the existing per-agent Stop path. Counts reflect changes; repeats return zero. Existing active stops retain their duration; resume clears any stored stop.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Changed-agent count and plain confirmation", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "count", "message" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/agents/{key_hash}/status": { "get": { "operationId": "agentStatus", "summary": "Read one agent’s current status", "description": "J176. Same active management or team owner/admin Bearer and target-key visibility as policy GET. Session, inference and read-only keys refused. AGENT_POLICY_ENABLED (default false); off 404. No writes. Work hours, timed Stop, unexpired pending approvals for this key, existing runway and optional quiet/Guard state. See /docs/#agent-status for limits.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "No-store data: key_hash, as_of, stopped, optional stopped_until, work_hours [{key_hash, inside, time_zone, outside, next_at (nullable)}], pending_approvals, runway (same as agentRunway), quiet ({hours, last_call_at (nullable)} or null), guard_paused. Quiet respects QUIET_AGENT_ALERTS_ENABLED; guard_paused respects AGENT_GUARD_ENABLED.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key_hash": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "stopped": { "type": "boolean" }, "stopped_until": { "type": "string", "format": "date-time" }, "work_hours": { "type": "array", "items": { "type": "object", "properties": { "key_hash": { "type": "string" }, "inside": { "type": "boolean" }, "time_zone": { "type": "string" }, "outside": { "enum": [ "refuse", "ask_first" ] }, "next_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "pending_approvals": { "type": "integer", "minimum": 0 }, "runway": { "$ref": "#/paths/~1api~1v1~1agents~1{key_hash}~1runway/get/responses/200/content/application~1json/schema/properties/data" }, "quiet": { "type": [ "object", "null" ], "properties": { "hours": { "type": "integer", "minimum": 1 }, "last_call_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "guard_paused": { "type": "boolean" } }, "required": [ "key_hash", "as_of", "stopped", "work_hours", "pending_approvals", "runway", "quiet", "guard_paused" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "AdminToken": { "type": "apiKey", "in": "header", "name": "x-admin-token", "description": "Operator ADMIN_TOKEN. Authorization: Bearer with the operator token is also accepted." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Anyroute API key", "description": "Send the key in Authorization. Never put it in a URL." }, "AnthropicApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Anthropic SDK style: the Anyroute key in x-api-key. Authorization: Bearer with the same key works too. Never put it in a URL." }, "WalletAuth": { "type": "apiKey", "in": "header", "name": "X-Wallet-Auth", "description": "Wallet authentication header for supported per-call flows." }, "PrivateToken": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Only where the router enables blind tokens. `PrivateToken token=`: one Privacy Pass token (RFC 9578 type 0x0002, 354 bytes) bought with POST /api/v1/blind/purchase. Each token can be spent once." } }, "parameters": { "Referer": { "name": "HTTP-Referer", "in": "header", "required": false, "schema": { "type": "string" } }, "Title": { "name": "X-Title", "in": "header", "required": false, "schema": { "type": "string" } }, "Payment": { "name": "X-Payment", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Payment for this exact request: a CallPay transaction hash, or an x402 payment (base64 JSON {x402Version, scheme, network, payload}) from a 402 quote. Do not replay blindly." }, "PaymentSignature": { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment for this exact request: base64 JSON PaymentPayload {x402Version: 2, resource, accepted, payload: {signature, authorization}} for the requirement in PAYMENT-REQUIRED. Read like X-Payment; do not replay blindly." }, "PaymentRecovery": { "name": "PAYMENT-RECOVERY", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{128,130}$" }, "description": "x402 payment recovery, where the router has x402 enabled: the payer's EIP-191 (personal_sign) signature of anyroute:x402-recovery:4663:: (lowercase hex). Sent with the same X-Payment or PAYMENT-SIGNATURE and the identical request after a paid answer was lost, it returns the answer kept for that payer and nonce byte for byte, with the same settlement headers, and never relays the payment again. Kept 24 hours. Refusals: 401 invalid_payment_recovery (not the payer's signature), 409 payment_request_mismatch (a different request), 404 payment_recovery_not_found with metadata.settled (nothing kept)." }, "PayWith": { "name": "X-Pay-With", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Configured Stock Token symbol for a key with an active session." }, "DisclosureMax": { "name": "X-Anyroute-Disclosure-Max", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "none", "policy", "any" ], "default": "any" }, "description": "Same as provider.disclosure. When both are given the stricter one applies." }, "Lane": { "name": "X-Anyroute-Lane", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "public", "attested", "unlinkable" ], "default": "public" }, "description": "Same as provider.lane. When both are given the stricter one applies. unlinkable is served only where the router enables Oblivious HTTP or serves the lane over its Tor onion service (otherwise 501), and then only through a relay, or through the onion service, with a blind token." }, "LaneDowngrade": { "name": "X-Anyroute-Lane-Downgrade", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "none", "attested" ], "default": "none" }, "description": "Same as provider.lane_downgrade: attested lets a request for lane unlinkable that carries an API key or a wallet be served on lane attested. none in either setting refuses the downgrade." }, "TlogKind": { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "receipt_key", "ohttp_key_config", "blind_issuer_key", "measurement_bundle", "attestation_binding", "data_inventory", "host_policy" ] } }, "TlogSha256": { "name": "sha256", "in": "query", "required": true, "description": "Lowercase hex SHA-256 of the key or configuration.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "ProjectTag": { "name": "X-Anyroute-Project", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]{1,48}$" }, "description": "C134: owner-chosen call label, lowercased; overrides the key default. Invalid labels return 400. The unlinkable lane refuses tags with project_unlinkable to prevent linking calls. Stored outside the signed receipt." }, "DecisionTag": { "name": "X-Anyroute-Decision-Tag", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^(sha256:)?[0-9a-fA-F]{64}$" }, "description": "Optional sha256:<64 hex>, for example the SHA-256 of the order intent this call informs. Signed into the receipt as payload.decision_tag and v2 claims.decision_tag. Refused with 400 invalid_decision_tag when malformed and 400 decision_tag_unlinkable on the unlinkable lane. Ignored while DECISION_TAGS_ENABLED is false (the default)." } }, "headers": { "RouteExplanation": { "description": "V84: compact JSON RouteExplanation, on chat/text completions and embeddings when ROUTE_EXPLAIN_ENABLED is true (default false; switched on at anyroute.tech). The signed receipt route claim has the same fields. Streams wait for the serving provider before sending this header and also deliver the claim in the final receipt. Cache and encrypted-chat paths omit it.", "schema": { "type": "string" } }, "Disclosure": { "description": "The disclosure class the answering provider was served under: attested (retention declared attested and a fresh TEE attestation), policy (a documented no-retention policy, no legal hold) or vendor-forwarded (anything else). On a stream it is sent only when every provider the request can reach shares one class; the signed receipt always carries it.", "schema": { "type": "string", "enum": [ "attested", "policy", "vendor-forwarded" ] } }, "LaneServed": { "description": "The lane the request was served under: public (any provider), attested (only providers under attested retention with a fresh attestation) or unlinkable (attested providers, reached through an Oblivious HTTP relay or over Tor through the router's onion service, and paid with a blind token). It is the lane the router enforced: the one the request asked for (or its key's or saved route's default), attested when an unlinkable request with a key allowed that downgrade, unlinkable for a relayed blind-token request that named none, and otherwise public.", "schema": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] } }, "ReceiptId": { "description": "The id of this generation's signed receipt: the same value as the response's id and receipt.id. Read the receipt with GET /api/v1/receipts/{id}. On a stream it is sent before the first chunk; the final event carries the receipt itself.", "schema": { "type": "string" } }, "InferenceId": { "description": "The same id as X-Receipt-Id, under the header name Hugging Face inference clients read.", "schema": { "type": "string" } }, "GenerationId": { "description": "The same id as X-Receipt-Id (GET /api/v1/generation?id=...).", "schema": { "type": "string" } }, "PolicyHash": { "description": "Present only when the serving endpoint's fresh, verified attestation bound the hash of the policy its in-enclave classifier enforces (\"sha256:<64 hex>\"). Omitted otherwise, and on a stream unless every endpoint the request can reach attested the same hash. The router relays the attested value; it never computes one.", "schema": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" } } }, "responses": { "ApiError": { "description": "OpenRouter-shaped API error. A 402 payment response may include payment metadata and is not a signal to repeat payment automatically.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Conflict": { "description": "Run active, slot already claimed or schedule limit reached. D136.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "BadRequest": { "description": "The request body, JSON or parameters failed validation. error.type is, for example, invalid_request, invalid_json or invalid_guardrails; do not retry the same request unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Unauthorized": { "description": "Authentication is missing or was rejected: no API key, an unknown, disabled or expired key, or invalid wallet authentication. error.type is missing_key, invalid_key, key_disabled, key_expired or invalid_wallet_auth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "PaymentRequired": { "description": "The call cannot be paid: the balance or the key's budget is insufficient (insufficient_credits, key_budget_exceeded), or a per-call payment is required or was not accepted (payment_required, payment_pending, payment_insufficient, payment_unknown_quote, payment_failed). A payment_required quote is in error.metadata and binds to this exact request; never repeat a payment automatically.", "headers": { "X-Payment-Required": { "description": "Present on a per-call payment quote; names the payment asset.", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Present on a per-call payment quote; carries the chain and quote nonce.", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "Present when the router has x402 enabled: the x402 v2 PaymentRequired (base64 JSON {x402Version: 2, error, resource, accepts}) for the same price as the body, with network eip155:4663 and amount in USDG base units.", "schema": { "type": "string" } }, "PAYMENT-RESPONSE": { "description": "x402 v2, only when the settlement transfer failed: base64 JSON {success: false, errorReason, transaction, network, payer}.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Forbidden": { "description": "The key is valid but may not do this: its role does not allow the action, or its model allowlist excludes the model. error.type is forbidden or model_not_allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "The model, provider route, key, team, generation or receipt does not exist or is not visible to the caller. error.type is, for example, not_found, model_not_found or no_providers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "DisclosureUnavailable": { "description": "409 disclosure_unavailable. No provider meets provider.disclosure, though the model has providers that would otherwise serve the request (a lane that no attested endpoint can serve is 503 no_attested_endpoint instead). On chat completions it can also be verification_unavailable: verify \"dual\" found fewer than two providers of the model that support temperature and seed (on lane attested: fewer than two different attested providers of the model). The request is never routed to a provider that does not meet the setting; nothing was sent to any provider and nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "LaneNotAvailable": { "description": "501 lane_not_available. Lane unlinkable is not available on this router: it needs the Oblivious HTTP gateway, or the lane over its Tor onion service, with blind tokens, which it does not run. Nothing was sent to any provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "DisclosureProviderDown": { "description": "503. no_attested_endpoint: lane attested or unlinkable, and no endpoint of the model with a fresh, verified attestation can serve it; error.metadata.reason is none_attested, or attested_endpoints_down (with Retry-After) when attested endpoints exist but are all in an outage. A council with an attested seat (a member or the judge) that has none is refused the same way, and error.metadata.council_seat names the seat. disclosure_provider_unavailable: providers that meet provider.disclosure exist but are all in an outage right now; retry after Retry-After. Either way the request is not routed to any other provider and nothing was charged.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "TooManyRequests": { "description": "A rate limit was reached (rate_limited). Wait for the Retry-After interval before retrying.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, when the limit reports it.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "AnthropicError": { "description": "Anthropic's error shape, for the Messages endpoints. error.type follows the status: 400 invalid_request_error, 401 authentication_error, 402 billing_error, 403 permission_error, 404 not_found_error, 413 request_too_large, 429 rate_limit_error (with Retry-After), 5xx api_error, 504 timeout_error. A status Anthropic does not define keeps its own (409 for a lane no provider can serve, 501 for a lane the router does not run) and sends X-Should-Retry: false. anyroute carries the router's own error type and metadata, and the receipt_id when a refused call was billed.", "headers": { "Request-Id": { "description": "An id for this request (req_...), also in the error body's request_id.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorBody" } } } }, "OllamaError": { "description": "Ollama's error shape, {\"error\": \"...\"}, with the router's status: 400 for a bad field (the message names it), 401 or 402 without a usable key, 404 for an unknown model (the message names one to use), 409 or 503 when the requested lane cannot be served, 429 with Retry-After, 501 for local-model operations, 502 when every provider failed before any output.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaErrorBody" } } } } }, "schemas": { "BusinessDetails": { "x-card": "H168", "type": "object", "additionalProperties": false, "description": "Optional user-entered business identity, outside the signed statement. Values are trimmed; address line endings normalized. Empty fields clear. No control characters except address newlines.", "properties": { "business_name": { "type": "string", "maxLength": 160, "default": "", "description": "Business name." }, "address": { "type": "string", "maxLength": 1000, "default": "", "description": "Multi-line postal address." }, "tax_id": { "type": "string", "maxLength": 120, "default": "", "description": "Free-text VAT, GST or EIN." }, "reference": { "type": "string", "maxLength": 240, "default": "", "description": "Purchase order or billing reference; no email addresses." } } }, "ScheduledPromptInput": { "x-card": "D136", "type": "object", "additionalProperties": false, "required": [ "name", "prompt", "model", "key_hash", "cadence", "max_cost_usd" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 64000, "description": "Complete prompt stored encrypted at rest under a router-held secret; Anyroute can read it." }, "model": { "type": "string", "maxLength": 200 }, "key_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "cadence": { "type": "string", "enum": [ "hourly", "daily", "monday" ] }, "time_utc": { "type": [ "string", "null" ], "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Required for daily and monday. UTC HH:MM; null for hourly." }, "max_cost_usd": { "oneOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, { "type": "string", "pattern": "^[0-9]+(\\.[0-9]{1,12})?$" } ], "description": "Required positive ceiling, at most 1000 USD; form starts at 0.05. Refused before inference if worst-case hold exceeds it." }, "paused": { "type": "boolean", "default": false } } }, "ScheduledPromptPatch": { "x-card": "D136", "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 64000, "description": "Complete prompt stored encrypted at rest under a router-held secret; Anyroute can read it." }, "model": { "type": "string", "maxLength": 200 }, "key_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "cadence": { "type": "string", "enum": [ "hourly", "daily", "monday" ] }, "time_utc": { "type": [ "string", "null" ], "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Required for daily and monday. UTC HH:MM; null for hourly." }, "max_cost_usd": { "oneOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, { "type": "string", "pattern": "^[0-9]+(\\.[0-9]{1,12})?$" } ], "description": "Required positive ceiling, at most 1000 USD; form starts at 0.05. Refused before inference if worst-case hold exceeds it." }, "paused": { "type": "boolean", "default": false } } }, "ScheduledPrompt": { "x-card": "D136", "allOf": [ { "$ref": "#/components/schemas/ScheduledPromptInput" }, { "type": "object", "properties": { "id": { "type": "string" }, "consecutive_failures": { "type": "integer" }, "next_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } ] }, "ScheduledPromptRun": { "x-card": "D136", "type": "object", "properties": { "id": { "type": "string" }, "due_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed" ] }, "reply": { "type": [ "string", "null" ], "description": "Full decrypted saved reply. Stored encrypted at rest, last ten runs only." }, "reason": { "type": [ "string", "null" ], "description": "Bounded refusal or failure code; no upstream error message." }, "generation_id": { "type": [ "string", "null" ] } } }, "AgentReplay": { "type": "object", "required": [ "window", "evaluated", "allowed", "denied", "asked", "by_reason", "actual", "changed", "examples", "truncated", "notes" ], "properties": { "window": { "type": "object", "required": [ "from", "to", "days" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "days": { "type": "integer" } } }, "evaluated": { "type": "integer" }, "allowed": { "type": "integer" }, "denied": { "type": "integer" }, "asked": { "type": "integer", "description": "Sent to ask me first; counted as not run." }, "stopped_at": { "type": "string", "format": "date-time", "description": "Present when the draft would have stopped the key; every later call is refused." }, "stopped_reason": { "type": "string" }, "by_reason": { "type": "object", "additionalProperties": { "type": "integer" } }, "actual": { "type": "object", "description": "What happened to the same calls and actions. not_recorded counts calls that ran with no rulebook decision.", "required": [ "allowed", "denied", "asked", "not_recorded" ], "properties": { "allowed": { "type": "integer" }, "denied": { "type": "integer" }, "asked": { "type": "integer" }, "not_recorded": { "type": "integer" } } }, "changed": { "type": "integer", "description": "Calls and actions whose replayed decision differs from the recorded one." }, "examples": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "time", "kind", "model", "lane", "action", "cost_usd", "decision", "reason", "actual" ], "properties": { "time": { "type": "string", "format": "date-time" }, "kind": { "enum": [ "call", "action" ] }, "model": { "type": [ "string", "null" ] }, "lane": { "type": [ "string", "null" ] }, "action": { "type": [ "string", "null" ] }, "cost_usd": { "type": "number" }, "decision": { "enum": [ "allow", "deny", "approval_required" ] }, "reason": { "oneOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, { "type": "null" } ] }, "actual": { "enum": [ "allow", "deny", "approval_required", null ] } } } }, "truncated": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "string" } } } }, "FacilitatorPaymentRequest": { "type": "object", "required": [ "paymentPayload", "paymentRequirements" ], "description": "The x402 facilitator request. v1: paymentPayload {x402Version 1, scheme, network, payload}; paymentRequirements with maxAmountRequired and resource. v2: paymentPayload {x402Version 2, resource, accepted, payload}; paymentRequirements with amount. Optional fee: paymentRequirements.extra.facilitatorFee {amount, payTo} and paymentPayload.payload.facilitatorFee {signature, authorization}.", "properties": { "x402Version": { "type": "integer", "enum": [ 1, 2 ] }, "paymentPayload": { "type": "object", "properties": { "x402Version": { "type": "integer", "enum": [ 1, 2 ] }, "scheme": { "type": "string" }, "network": { "type": "string" }, "accepted": { "type": "object" }, "resource": { "type": "object" }, "payload": { "type": "object", "required": [ "signature", "authorization" ], "properties": { "signature": { "type": "string" }, "authorization": { "type": "object", "required": [ "from", "to", "value", "validAfter", "validBefore", "nonce" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string" }, "validAfter": { "type": "string" }, "validBefore": { "type": "string" }, "nonce": { "type": "string" } } } } } } }, "paymentRequirements": { "type": "object", "required": [ "scheme", "network", "payTo", "asset" ], "properties": { "scheme": { "type": "string", "enum": [ "exact" ] }, "network": { "type": "string", "example": "eip155:4663" }, "maxAmountRequired": { "type": "string" }, "amount": { "type": "string" }, "resource": { "type": "string" }, "payTo": { "type": "string" }, "asset": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object" } } } } }, "FacilitatorVerifyResponse": { "type": "object", "required": [ "isValid", "payer" ], "properties": { "isValid": { "type": "boolean" }, "invalidReason": { "type": "string" }, "invalidMessage": { "type": "string" }, "payer": { "type": "string" } } }, "FacilitatorSettleResponse": { "type": "object", "required": [ "success", "transaction", "network", "payer" ], "properties": { "success": { "type": "boolean" }, "errorReason": { "type": "string" }, "errorMessage": { "type": "string" }, "transaction": { "type": "string", "description": "Relay transaction hash; empty when nothing was settled." }, "network": { "type": "string" }, "payer": { "type": "string" }, "receipt": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" } } } } }, "FacilitatorSupported": { "type": "object", "required": [ "kinds", "signers", "policy" ], "properties": { "kinds": { "type": "array", "items": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "scheme": { "type": "string" }, "network": { "type": "string" } } } }, "extensions": { "type": "array", "items": { "type": "string" } }, "signers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "policy": { "type": "object" } } }, "FacilitatorDiscovery": { "type": "object", "required": [ "x402Version", "items", "pagination" ], "properties": { "x402Version": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string" }, "type": { "type": "string" }, "x402Version": { "type": "integer" }, "accepts": { "type": "array", "items": { "type": "object" } }, "lastUpdated": { "type": "string", "format": "date-time" }, "metadata": { "type": "object" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } }, "FacilitatorListingRequest": { "type": "object", "required": [ "payTo", "resource", "issuedAt", "signature" ], "properties": { "payTo": { "type": "string" }, "resource": { "type": "string", "format": "uri" }, "priceHint": { "type": "string", "description": "USDG base units; 0 for none." }, "outputSchema": { "type": "string", "description": "The exact JSON text that was signed, or empty." }, "tags": { "type": "array", "maxItems": 10, "items": { "type": "string" } }, "listed": { "type": "boolean", "default": true }, "issuedAt": { "type": "integer", "description": "Unix seconds." }, "signature": { "type": "string" } } }, "FacilitatorListing": { "type": "object", "properties": { "id": { "type": "string" }, "payTo": { "type": "string" }, "resource": { "type": "string" }, "priceHint": { "type": [ "string", "null" ] }, "outputSchema": { "type": [ "object", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "listed": { "type": "boolean" }, "signedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "FacilitatorReceipt": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "facilitator.settle" ] }, "status": { "type": "string" }, "transaction": { "type": [ "string", "null" ] }, "alg": { "type": "string" }, "kid": { "type": [ "string", "null" ] }, "cose": { "type": "string" }, "claims": { "type": "object" }, "leaf": { "type": [ "string", "null" ] }, "anchor": { "type": [ "object", "null" ] } } } } }, "NetworkStats": { "type": "object", "required": [ "as_of", "cache_seconds", "hosts", "attested_hosts", "capacity", "tokens", "bonds", "interest", "policy_version" ], "properties": { "as_of": { "type": "string", "format": "date-time" }, "cache_seconds": { "type": "integer", "const": 30 }, "hosts": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "probation": { "type": "integer", "minimum": 0 }, "live": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 } }, "required": [ "total", "probation", "live", "rejected" ] }, "attested_hosts": { "type": "integer", "minimum": 0 }, "capacity": { "type": "object", "properties": { "model_count": { "type": "integer", "minimum": 0 }, "models": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "string" } }, "required": [ "model_count", "models", "definition" ] }, "tokens": { "type": "object", "properties": { "public_lane": { "type": "object", "properties": { "days_7": { "type": [ "object", "null" ], "properties": { "lower": { "type": "string", "pattern": "^[0-9]+$" }, "upper_exclusive": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "lower", "upper_exclusive" ] }, "days_30": { "type": [ "object", "null" ], "properties": { "lower": { "type": "string", "pattern": "^[0-9]+$" }, "upper_exclusive": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "lower", "upper_exclusive" ] }, "bucket_size": { "type": "string", "const": "100000" } }, "required": [ "days_7", "days_30", "bucket_size" ] }, "private_lanes": { "type": "null" }, "dp_stats_url": { "type": "string", "const": "/api/v1/stats" }, "definition": { "type": "string" } }, "required": [ "public_lane", "private_lanes", "dp_stats_url", "definition" ] }, "bonds": { "type": [ "object", "null" ], "properties": { "total_units": { "type": "string", "pattern": "^[0-9]+$" }, "active_units": { "type": "string", "pattern": "^[0-9]+$" }, "asset": { "type": "string", "const": "USDG" }, "decimals": { "type": "integer", "const": 6 }, "fresh": { "type": "boolean" }, "indexed_block": { "type": [ "string", "null" ] } }, "required": [ "total_units", "active_units", "asset", "decimals", "fresh", "indexed_block" ] }, "interest": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "by_role": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "by_region": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "readiness_mentions": { "type": "integer", "minimum": 0 } }, "required": [ "total", "by_role", "by_region", "readiness_mentions" ] }, "policy_version": { "type": [ "integer", "null" ], "minimum": 1 } } }, "AgentApproval": { "type": "object", "properties": { "approval_context": { "type": "array", "items": { "type": "string" }, "description": "J185: optional shared context lines on lists when AGENT_APPROVAL_CONTEXT_ENABLED (default false). Spend today, daily caps, estimate if used, current work hours, requests since Monday UTC and approved among them, retained duplicate/rotation metadata. No prompt or tool arguments. Status/decision responses are unchanged." }, "can_allow": { "type": "boolean", "description": "E153: present on approval lists only when AGENT_TEAM_APPROVERS_ENABLED; true for owners/admins with rulebook access." }, "id": { "type": "string" }, "key_hash": { "type": "string" }, "intent": { "description": "Routing identifiers, output limit and estimated cost only. Multi-model requests contain an intents array. No prompt or response fields.", "type": "object" }, "intent_hash": { "type": "string" }, "max_cost_pico": { "type": "string", "pattern": "^[0-9]+$" }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired", "used" ] }, "requested_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "decided_by": { "type": [ "string", "null" ] }, "used_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "key_hash", "intent", "intent_hash", "max_cost_pico", "status", "requested_at", "expires_at", "decided_at", "decided_by", "used_at" ] }, "AgentBreakers": { "type": "object", "additionalProperties": false, "properties": { "max_spend_usd_per_minute": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "max_requests_per_minute": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "max_denials_per_10min": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "max_distinct_models_per_hour": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "description": "Optional rolling recorded-state circuit breakers. Inclusive thresholds trip the router kill switch before the next admission with reason breaker: and HTTP 403 agent_killed; no charge for the refused request. Account locking serializes observations, including inherited session admissions. Manual principal resume resets breaker observations and spend window, not cap spend. Recorded spend includes open usage reservations; in-flight work may finish. Only requests through AnyRoute. AGENT_POLICY_ENABLED defaults false." }, "AgentPolicy": { "type": "object", "properties": { "work_hours": { "description": "G161: Optional wall-clock work hours. Start included, end excluded; overnight windows belong to their starting day. Repeated DST minutes both count and skipped minutes do not exist. Other refusals and existing UTC windows take precedence. Refusal reasons include the next opening; ask_first uses the existing single-use approval path.", "type": "object", "additionalProperties": false, "required": [ "days", "start", "end", "time_zone", "outside" ], "properties": { "days": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "start": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$", "description": "Must differ from end." }, "end": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "time_zone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA time zone validated using Intl, for example America/New_York." }, "outside": { "type": "string", "enum": [ "refuse", "ask_first" ] } } }, "alerts": { "type": "object", "additionalProperties": false, "properties": { "at_percent": { "type": "array", "maxItems": 64, "items": { "type": "integer", "minimum": 1, "maximum": 100 }, "default": [ 80, 100 ] }, "denials_in_10min": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 5 }, "channels": { "type": "array", "maxItems": 3, "items": { "enum": [ "webhook", "email", "telegram" ] }, "default": [ "webhook", "telegram" ] } }, "description": "Optional opt-in. Omission preserves behavior and hashes; empty object uses defaults. Reuses linked channels; email has no destination." }, "version": { "type": "number", "const": 1 }, "models": { "type": "object", "properties": { "allow": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "deny": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "additionalProperties": false }, "lanes": { "maxItems": 64, "type": "array", "items": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] } }, "caps": { "type": "object", "properties": { "per_request_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "per_hour_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "per_day_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "per_week_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "max_output_tokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 } }, "additionalProperties": false }, "tools": { "type": "object", "properties": { "allow": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "deny": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "additionalProperties": false }, "windows": { "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "days": { "maxItems": 64, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "start": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "days", "start", "end" ], "additionalProperties": false } }, "approval": { "type": "object", "properties": { "above_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "above_calls_per_hour": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Optional. Ask the principal first once the rolling hour already holds this many model calls the rulebook admitted, plus approvals used (reason approval_calls_per_hour)." } }, "required": [ "above_usd" ], "additionalProperties": false }, "on_breach": { "type": "string", "enum": [ "deny", "kill" ] }, "autonomy": { "type": "object", "additionalProperties": false, "required": [ "rungs", "demote_on" ], "properties": { "rungs": { "type": "array", "minItems": 1, "maxItems": 5, "description": "Requirements cannot decrease; spending multipliers must strictly increase above 1. Both thresholds apply at each rung.", "items": { "type": "object", "additionalProperties": false, "required": [ "after_days", "clean_requests", "caps_multiplier" ], "properties": { "after_days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "clean_requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caps_multiplier": { "type": "number", "exclusiveMinimum": 1, "maximum": 10 } } } }, "demote_on": { "type": "array", "maxItems": 3, "items": { "type": "string", "enum": [ "deny", "kill", "breaker" ] } } } }, "breakers": { "$ref": "#/components/schemas/AgentBreakers" } }, "required": [ "version", "models", "caps", "on_breach" ], "additionalProperties": false }, "AgentIntent": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "model", "lane", "est_cost_pico", "tools" ], "properties": { "kind": { "const": "inference" }, "model": { "type": "string", "minLength": 1, "maxLength": 160 }, "lane": { "enum": [ "public", "attested", "unlinkable" ] }, "est_cost_pico": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer pico-USD, 1 USD = 10^12 pico." }, "max_output_tokens": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "tools": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "maxItems": 64 } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "name" ], "properties": { "kind": { "const": "mcp_tool" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } } ] }, "AgentDecision": { "type": "object", "required": [ "decision", "reasons" ], "properties": { "decision": { "enum": [ "allow", "deny", "approval_required" ] }, "reasons": { "type": "array", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "enum": [ "killed", "model_not_allowed", "lane_not_allowed", "over_per_request", "over_per_hour", "over_per_day", "over_per_week", "max_tokens", "tool_not_allowed", "outside_window", "approval_required", "breaker:max_spend_usd_per_minute", "breaker:max_requests_per_minute", "breaker:max_denials_per_10min", "breaker:max_distinct_models_per_hour" ] }, "message": { "type": "string" } } } } } }, "Playbook": { "type": "object", "required": [ "id", "name", "team_id", "policy", "sha256", "version", "followers", "keys", "can_edit" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 }, "team_id": { "type": [ "string", "null" ], "description": "The owning team, or null for an account-wide playbook." }, "policy": { "$ref": "#/components/schemas/AgentPolicy" }, "sha256": { "type": "string", "description": "SHA-256 of the canonical rules; each following key's rulebook carries the same digest." }, "version": { "type": "integer", "minimum": 1, "description": "1 at creation, plus one for each change of rules. A rename keeps it." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string", "description": "Hash of the key that made the last change." }, "followers": { "type": "integer", "minimum": 0, "description": "Every key that follows the playbook." }, "keys": { "type": "array", "description": "The following keys the caller manages.", "items": { "type": "object", "required": [ "key_hash", "name" ], "properties": { "key_hash": { "type": "string" }, "name": { "type": [ "string", "null" ] } } } }, "can_edit": { "type": "boolean" } } }, "PlaybookInput": { "type": "object", "additionalProperties": false, "required": [ "name", "policy" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "policy": { "$ref": "#/components/schemas/AgentPolicy" }, "team_id": { "type": [ "string", "null" ], "description": "Management keys only: a team the account owns." } } }, "PlaybookUpdate": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "policy": { "$ref": "#/components/schemas/AgentPolicy" } } }, "PlaybookChange": { "type": "object", "required": [ "action", "version", "sha256", "name", "followers", "at" ], "properties": { "action": { "type": "string", "enum": [ "create", "update", "rename", "delete" ] }, "version": { "type": "integer" }, "sha256": { "type": "string" }, "name": { "type": "string" }, "followers": { "type": "integer", "minimum": 0 }, "at": { "type": "string", "format": "date-time" } } }, "PlaybookFollow": { "type": "object", "additionalProperties": false, "required": [ "playbook_id" ], "properties": { "playbook_id": { "type": [ "string", "null" ] } } }, "PlaybookFollowResult": { "type": "object", "required": [ "key_hash", "changed", "playbook", "policy", "sha256", "killed", "playbook_id" ], "properties": { "key_hash": { "type": "string" }, "changed": { "type": "boolean" }, "playbook": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "integer" } } }, "policy": { "oneOf": [ { "$ref": "#/components/schemas/AgentPolicy" }, { "type": "null" } ] }, "sha256": { "type": [ "string", "null" ] }, "killed": { "type": "boolean" }, "playbook_id": { "type": [ "string", "null" ] } } }, "AgentPolicyResult": { "type": "object", "required": [ "policy", "sha256", "version", "killed" ], "properties": { "policy": { "$ref": "#/components/schemas/AgentPolicy" }, "sha256": { "type": "string" }, "version": { "const": 1 }, "stopped_until": { "type": "string", "format": "date-time", "description": "B117: Present only on a timed stop; omitted on running or indefinitely stopped policies." }, "killed": { "type": "boolean" }, "killed_at": { "type": [ "string", "null" ], "format": "date-time" }, "killed_reason": { "type": [ "string", "null" ] }, "playbook_id": { "type": "string", "description": "Present only while the key follows a playbook (POST /api/v1/agents/{key_hash}/playbook); its rules are then that playbook's current rules." } } }, "HostPublic": { "type": "object", "additionalProperties": false, "properties": { "admission": { "type": [ "object", "null" ], "description": "Null for curated providers. Approval requires admitted probation/live status, no refusal reasons and a fresh successful latest hardware attestation plus the recorded checked policy.", "required": [ "status", "policy_version", "reasons", "checked_at" ], "properties": { "status": { "type": "string", "enum": [ "approved", "not_approved" ] }, "policy_version": { "type": [ "integer", "null" ], "minimum": 1, "description": "Version recorded by admission or renewal, not necessarily the latest published policy." }, "reasons": { "type": "array", "items": { "type": "string" } }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "id": { "type": "string" }, "name": { "type": "string" }, "tee_kind": { "type": "string" }, "attested": { "type": "boolean" }, "status": { "type": "string" }, "probation": { "type": "boolean" }, "shadow_until": { "type": [ "string", "null" ] }, "models": { "type": "array", "items": { "type": "string" } }, "attestation": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "attested", "unverified" ] }, "reason": { "type": "string" }, "tee": { "type": [ "string", "null" ] }, "verifiers": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ] }, "last_attempt_at": { "type": [ "string", "null" ] }, "last_attempt_ok": { "type": [ "boolean", "null" ] } }, "required": [ "status", "tee", "verifiers", "last_verified_at", "last_attempt_at", "last_attempt_ok" ] }, "verify_url": { "type": "string" } }, "required": [ "id", "name", "tee_kind", "attested", "status", "probation", "shadow_until", "models", "attestation", "verify_url" ] }, "HostDetail": { "type": "object", "additionalProperties": false, "properties": { "admission": { "type": [ "object", "null" ], "description": "Null for curated providers. Approval requires admitted probation/live status, no refusal reasons and a fresh successful latest hardware attestation plus the recorded checked policy.", "required": [ "status", "policy_version", "reasons", "checked_at" ], "properties": { "status": { "type": "string", "enum": [ "approved", "not_approved" ] }, "policy_version": { "type": [ "integer", "null" ], "minimum": 1, "description": "Version recorded by admission or renewal, not necessarily the latest published policy." }, "reasons": { "type": "array", "items": { "type": "string" } }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "id": { "type": "string" }, "name": { "type": "string" }, "tee_kind": { "type": "string" }, "attested": { "type": "boolean" }, "status": { "type": "string" }, "probation": { "type": "boolean" }, "shadow_until": { "type": [ "string", "null" ] }, "models": { "type": "array", "items": { "type": "string" } }, "attestation": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "attested", "unverified" ] }, "reason": { "type": "string" }, "tee": { "type": [ "string", "null" ] }, "verifiers": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ] }, "last_attempt_at": { "type": [ "string", "null" ] }, "last_attempt_ok": { "type": [ "boolean", "null" ] }, "checks": { "type": "object", "description": "The existing attestation endpoint checks." }, "not_checked": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "tee", "verifiers", "last_verified_at", "last_attempt_at", "last_attempt_ok", "checks", "not_checked" ] }, "verify_url": { "type": "string" }, "attestation_history": { "type": [ "object", "null" ], "description": "First 50 sanitized events from the existing attestation history endpoint, with data, next cursor, history_days and url. Null when history is disabled." }, "measurement": { "type": [ "object", "null" ], "description": "Existing attestation endpoint current measurement: digests, status, timestamps, hardware registers, registry state and transparency_log with Rekor entry_url and verification checks; no raw quote." }, "measurement_history": { "type": "array", "items": { "type": "object", "description": "Existing attestation endpoint superseded measurements, each with its own superseded_at and transparency_log entry_url." } }, "anchoring": { "type": "object", "additionalProperties": false, "properties": { "roots": { "type": "integer", "minimum": 0 }, "anchored_roots": { "type": "integer", "minimum": 0 }, "latest": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer", "minimum": 0 }, "root": { "type": "string" }, "status": { "type": "string", "enum": [ "local", "pending", "confirmed" ] }, "anchored": { "type": "boolean" }, "tx_hash": { "type": [ "string", "null" ] }, "block_number": { "type": [ "integer", "null" ] }, "from_ts": { "type": "string" }, "to_ts": { "type": "string" }, "receipts": { "type": "integer", "minimum": 0 }, "attestation_ref": { "type": "string" } }, "required": [ "id", "root", "status", "anchored", "tx_hash", "block_number", "from_ts", "to_ts", "receipts", "attestation_ref" ] }, { "type": "null" } ] } }, "required": [ "roots", "anchored_roots", "latest" ] }, "uptime": { "type": "object", "additionalProperties": false, "properties": { "success_pct_30d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "observations_30d": { "type": "integer", "minimum": 0 }, "definition": { "type": "string" } }, "required": [ "success_pct_30d", "observations_30d", "definition" ] }, "proof_time": { "type": [ "object", "null" ], "description": "Existing proof-time summary metadata (generated_at, history_days, fresh_within_ms) and its host record. Host is null when absent from that summary. Proof-time itself is null when history is disabled." }, "earnings": { "type": "object", "additionalProperties": false, "properties": { "band": { "type": "string", "enum": [ "none yet", "<$1", "$1–10", "$10–100", "$100–1,000", "$1,000+" ] }, "basis": { "type": "string" } }, "required": [ "band", "basis" ] }, "operator": { "type": "object", "additionalProperties": false, "properties": { "payout_address": { "type": [ "string", "null" ] }, "payout_mode": { "type": "string" }, "invoiced_usdg_units": { "type": "string", "pattern": "^[0-9]+$" }, "unpaid_usdg_units": { "type": "string", "pattern": "^[0-9]+$" }, "decimals": { "type": "integer", "const": 6 } }, "required": [ "payout_address", "payout_mode", "invoiced_usdg_units", "unpaid_usdg_units", "decimals" ], "description": "Present only after walletAuth recovers the stored provider operator. Lifetime invoice units include paid invoices; unpaid units have no recorded payment transaction and can include a pending payout." } }, "required": [ "id", "name", "tee_kind", "attested", "status", "probation", "shadow_until", "models", "attestation", "verify_url", "attestation_history", "measurement", "measurement_history", "anchoring", "uptime", "proof_time", "earnings" ] }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "suggested_models": { "description": "B121: optional availability-error alternatives; empty if none match. Never switches models or charges. Messages also returns this top-level field; Responses stream errors carry it in the error event and response.error.", "type": "array", "maxItems": 3, "items": { "type": "object", "required": [ "id", "name", "prompt_price", "completion_price", "why" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prompt_price": { "type": "string", "description": "Dollars per input token" }, "completion_price": { "type": "string", "description": "Dollars per output token" }, "why": { "type": "string" } } } }, "error": { "type": "object", "required": [ "code", "message", "type" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "type": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } }, "Model": { "description": "When UPSTREAM_MONITOR_ENABLED is on, availability is temporarily_unavailable if every eligible provider account has a last successful USD balance at or below UPSTREAM_BALANCE_EXHAUSTED_USD (default 0). This optional field is omitted otherwise. A failed check retains an exhausted state until a later reading exceeds the threshold. Account balances remain operator-only.", "type": "object", "required": [ "id", "name", "created", "description", "context_length", "architecture", "pricing", "supported_parameters" ], "properties": { "performance": { "type": "object", "description": "E150: present only with health=recent. Best measured route median latency and throughput over 30 minutes, with at least three successful readings per metric; latency is first-token time for streams, full-response time otherwise. Observation-weighted model success rate across eligible funded routes over 30 days, including probes, excluding client rejections and rate limits; no routing prior. Unknown metrics are null. Speed is in memory and empty after restart.", "properties": { "latency_p50_ms": { "type": "number", "nullable": true, "minimum": 0 }, "throughput_p50_tps": { "type": "number", "nullable": true, "minimum": 0 }, "speed_window_seconds": { "type": "integer", "enum": [ 1800 ] }, "uptime_percent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "uptime_window_days": { "type": "integer", "enum": [ 30 ] }, "uptime_observations": { "type": "integer", "minimum": 0 } } }, "added_at": { "type": "integer", "format": "int64", "nullable": true, "description": "C131: first catalogue observation in Unix seconds. Null for baseline models whose arrival is unknown. Present only when MODEL_ARRIVALS_ENABLED is on (default false). Independent of created; removed/reintroduced IDs keep their original observation." }, "availability": { "type": "string", "enum": [ "temporarily_unavailable" ], "description": "Optional; all eligible upstream accounts are exhausted. Omitted otherwise." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "vision", "imageOut", "audio", "tools", "longContext", "attested", "network", "encrypted" ] }, "description": "Shared catalogue tags; longContext means at least 128,000 tokens. network requires a live fresh-attested network-host offer for an admitted model. encrypted requires the separate enabled gateway path, exact model ID and fresh evidence; ordinary chat remains readable by the router." }, "provider_names": { "type": "array", "items": { "type": "string" }, "description": "Names of providers with live servable offers for this model." }, "id": { "type": "string" }, "name": { "type": "string" }, "created": { "type": "integer" }, "description": { "type": "string" }, "context_length": { "type": "integer" }, "architecture": { "type": "object" }, "pricing": { "type": "object", "description": "Prices are returned as decimal strings per token; consult the live response." }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "data_policy": { "type": "object" }, "attested_available": { "type": "boolean" }, "lanes": { "type": "array", "items": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] }, "description": "The lanes this model can be served on right now: public whenever it has a live endpoint; attested while one of its endpoints has attested retention and a fresh, verified attestation; unlinkable as well where the router serves that lane (Oblivious HTTP, or its Tor onion service). The endpoints listing carries the same field per endpoint." }, "disclosure": { "type": "object", "description": "How many live endpoints are served under each disclosure class right now.", "properties": { "best": { "type": [ "string", "null" ], "enum": [ "attested", "policy", "vendor-forwarded", null ] }, "endpoints": { "type": "object", "properties": { "attested": { "type": "integer" }, "policy": { "type": "integer" }, "vendor-forwarded": { "type": "integer" } } } } }, "creator": { "type": [ "string", "null" ], "description": "Address that receives the model's creator royalty, once claimed." }, "royalty_bps": { "type": "integer", "description": "Creator royalty in basis points of the notional price; 0 until a creator is recorded." }, "variant": { "type": "string", "enum": [ "mainstream", "native_low_refusal", "abliterated" ], "description": "native_low_refusal and abliterated are restricted: they are routed only to providers served under attested retention with a fresh attestation whose attestation reported the in-enclave hard-block classifier as enabled. Whatever lane or disclosure setting a request carries, and however the provider is pinned, they are never sent to a public or vendor-forwarded provider." }, "variant_source": { "type": "string", "enum": [ "declared", "candidate", "inferred", "default" ], "description": "declared: an operator recorded the variant. candidate: the model is the weights of a day-zero candidate. inferred: nobody has classified the model and its name says its refusals were removed, so it is treated as abliterated. default: no record, treated as mainstream." }, "license": { "type": [ "string", "null" ], "description": "License identifier from the weights' model card, when an operator recorded one." }, "base_model": { "type": [ "string", "null" ], "description": "The model these weights derive from." }, "weights": { "type": [ "object", "null" ], "description": "Where the weights came from, as recorded by the operator.", "properties": { "source": { "type": [ "string", "null" ], "description": "For example huggingface:owner/repo." }, "revision": { "type": [ "string", "null" ], "description": "Commit the weights were taken from." }, "digest": { "type": [ "string", "null" ], "description": "sha256: of the weights, when recorded (for a day-zero model, the model digest in the provider's verified attestation)." } } }, "creator_handle": { "type": [ "string", "null" ], "description": "Hugging Face handle of the uploader." }, "attestation": { "$ref": "#/components/schemas/ModelAttestation" }, "datacenter_region": { "type": [ "string", "null" ], "description": "The one datacenter region every live endpoint of the model reports; null when any endpoint does not report one or they differ." }, "routing_variants": { "type": "array", "items": { "type": "string", "enum": [ "nitro", "floor", "free", "private" ] }, "description": "Model suffixes that change how this model is routed right now: nitro (fastest providers first, as provider.sort throughput) and floor (cheapest first, as provider.sort price) always; free while a free endpoint serves it; private while an endpoint has a fresh TEE attestation." } } }, "ModelAttestation": { "type": [ "object", "null" ], "description": "What the strongest live endpoint serving the model has proven. Every value comes from the router's own attestation and measurement records; a value that is not known is null, never filled in. null when no endpoint serves the model.", "required": [ "best", "manifest_ref", "exec_profile_id", "policy_hash" ], "properties": { "best": { "type": "string", "enum": [ "attested", "policy", "vendor-forwarded" ], "description": "The strongest disclosure class any live endpoint is served under right now (the same value as disclosure.best)." }, "manifest_ref": { "type": [ "object", "null" ], "description": "Where that endpoint's measured image is recorded, while its attestation is fresh. null when neither is known.", "properties": { "rekor_entry": { "type": [ "string", "null" ], "description": "The transparency log entry uuid, once its inclusion proof was checked." }, "registry_tx": { "type": [ "string", "null" ], "description": "The on-chain MeasurementRegistry transaction, once the registry reports the measurement." } } }, "exec_profile_id": { "type": [ "string", "null" ], "description": "The attested execution profile. null until an attestation the router checks reports one." }, "policy_hash": { "type": [ "string", "null" ], "description": "The classifier policy hash that endpoint's fresh attestation bound (as sent in X-Anyroute-Policy-Hash), else null." } } }, "StructuredOutputOptions": { "type": "object", "properties": { "json_check": { "type": "string", "enum": [ "validate", "repair" ], "description": "V83: Requires STRUCTURED_OUTPUT_CHECK_ENABLED (default false; switched on at anyroute.tech). validate checks the final JSON; repair permits one correction by the same routed model/provider. Both calls are billed normally. Streaming repair validates only. Requires json_object or json_schema and n=1; no council or dual verification. Non-streaming repair requires a bearer API key and bypasses the response cache. Explicit request settings override preset defaults." } } }, "StructuredOutputIssue": { "type": "object", "required": [ "path", "reason" ], "properties": { "path": { "type": "string", "description": "JSON Pointer path; empty string is the root." }, "reason": { "type": "string" } } }, "StructuredOutputResult": { "type": "object", "description": "V83: Unsigned response metadata; not written to generation receipts or returned by receipt lookup. Existing batch outputs may retain it with the answer. Original signed payload/sig/v2 stay intact. Top-level usage is for the returned call only; total_cost includes both served calls even if the correction is invalid. Checks do not establish factual accuracy. Supported schema assertions: type (including arrays), nullable, properties, required, additionalProperties, items, enum, const, anyOf, minLength/maxLength, minimum/maximum/exclusiveMinimum/exclusiveMaximum, minItems/maxItems, minProperties/maxProperties, and existing local #/ references via $defs/definitions. Unknown assertions are refused before billing. Limits: 1 MiB answer, 4096 schema nodes, 100000 validation steps, 64 levels, 16 reported errors. Oversized/non-text answers cannot be repaired.", "required": [ "mode", "valid", "errors", "retry_attempted", "calls", "total_cost" ], "properties": { "mode": { "type": "string", "enum": [ "validate", "repair" ] }, "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredOutputIssue" } }, "initial_errors": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredOutputIssue" } }, "retry_attempted": { "type": "boolean" }, "retry_error": { "type": "object", "description": "Correction did not return a usable answer. The first charge remains, and a signed correction charge is included even if its attestation was refused after settlement. status when known, reason." }, "repair_supported": { "type": "boolean", "description": "false for streaming repair; no second call is made." }, "note": { "type": "string" }, "calls": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "type": "object", "required": [ "attempt", "cost", "receipt" ], "properties": { "attempt": { "type": "integer", "minimum": 1, "maximum": 2 }, "cost": { "type": "string", "description": "Exact USDG charge for this call." }, "receipt": { "$ref": "#/components/schemas/Receipt" } } } }, "total_cost": { "type": "string", "description": "Sum of the served calls' USDG charges." } } }, "ChatRequest": { "type": "object", "required": [ "messages" ], "anyOf": [ { "required": [ "model" ] }, { "required": [ "models" ] } ], "properties": { "anyroute": { "$ref": "#/components/schemas/StructuredOutputOptions" }, "model": { "type": "string", "description": "Public model ID, optionally with routing suffixes: :nitro sorts providers by throughput (fastest first) and :floor by price (cheapest first), the same as provider.sort throughput and price and winning over it; both only order the providers the other preferences and the lane allow. :free and :private also apply. The reserved ID anyroute/council selects council mode when the router enables it. @route/ calls a saved route and @preset/ (or @preset/@ to pin one version) calls a preset of the key's account. @character/ calls a character: the card is the prompt and models[0], or the character's default model, answers." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Ordered candidate model IDs." }, "messages": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool", "function" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array" }, { "type": "null" } ] } } } }, "stream": { "type": "boolean", "default": false }, "max_tokens": { "type": "integer", "minimum": 1 }, "max_completion_tokens": { "type": "integer", "minimum": 1 }, "tools": { "type": "array", "items": { "type": "object" }, "description": "Requires a model/provider that supports tools." }, "tool_choice": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "response_format": { "type": "object", "description": "Requires a model/provider that supports the requested response format." }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" }, "council": { "$ref": "#/components/schemas/CouncilRequest" }, "verify": { "type": "string", "enum": [ "dual" ], "description": "Send the same request to two providers of the model at temperature 0 with a fixed seed and compare the outputs. Both calls are billed. Needs the router's council feature; not combinable with stream, models, cache or n above 1. Provider preferences, disclosure ceiling and lane apply to both calls. With lane attested the two calls go to two different attested providers of the model (retention declared attested, attestation fresh); each receipt then records its provider's attestation as payload.attestation_ref, and the verification field carries attested and attestation_refs next to agree. If two such providers do not exist the answer is 409, and nothing is sent or charged." } }, "additionalProperties": true }, "CouncilRequest": { "type": "object", "description": "Used with model anyroute/council. Members are called in parallel through the normal routing path, then the judge chooses one answer (judge) or writes a final one (fuse). Every call is billed and receipted; the worst case of all calls is held up front. provider preferences, including a disclosure ceiling or lane, apply to every member and to the judge.", "properties": { "models": { "type": "array", "minItems": 2, "maxItems": 5, "uniqueItems": true, "items": { "type": "string" }, "description": "Member model IDs. Falls back to the router's configured default when omitted." }, "judge": { "type": "string", "description": "Model ID of the judge. Falls back to the router's configured default when omitted." }, "mode": { "type": "string", "enum": [ "judge", "fuse" ], "default": "judge", "description": "judge returns one member's answer unchanged; fuse returns the judge's own text and does not support tools or response_format." }, "max_cost_usd": { "type": "number", "exclusiveMinimum": 0, "description": "Refuse the request with 402 council_budget_exceeded unless the worst case of every call fits. Lower max_tokens to fit." }, "min_members": { "type": "integer", "minimum": 2, "description": "Members that must answer before the judge runs. Defaults to 2." }, "attested": { "type": "boolean", "default": false, "description": "true holds every member and the judge to the attested lane (retention declared attested and a fresh attestation the router verified), the same as provider.lane attested for the whole council. Nothing is downgraded or dropped: a member, or the judge, with no attested provider refuses the request with 503 no_attested_endpoint, and nothing is sent or charged. The response then carries attested and attestation_refs in council, and each call's receipt carries attestation_ref. A production router has few attested providers today, so this often returns that 503." } }, "additionalProperties": false }, "CouncilResult": { "type": "object", "description": "Present on council responses. The top-level receipt is the judge's call and its signed payload carries the same members list; its disclosure is the weakest class among all the calls.", "properties": { "mode": { "type": "string", "enum": [ "judge", "fuse" ] }, "members": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "disclosure": { "type": "string", "enum": [ "attested", "policy", "vendor-forwarded" ], "description": "The class this member was served under." }, "receipt_id": { "type": [ "string", "null" ], "description": "Null for a member that failed; it was not billed." }, "cost": { "type": "string", "description": "USD charged for this member." }, "latency_ms": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "ok", "failed" ] }, "error": { "type": "string" } } } }, "judge": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "attested", "policy", "vendor-forwarded" ] }, "receipt_id": { "type": "string" }, "cost": { "type": "string" }, "latency_ms": { "type": "integer" }, "request_sha256": { "type": "string" } } }, "selected": { "type": [ "object", "null" ], "properties": { "label": { "type": "string" }, "receipt_id": { "type": "string" } } }, "outcome": { "type": "string", "enum": [ "selected", "fused" ] }, "members_cost": { "type": "string" }, "total_cost": { "type": "string", "description": "USD charged across every member and the judge." }, "answer_sha256": { "type": "string" }, "attested": { "type": "boolean", "description": "Present when the council ran on the attested lane (council.attested true, or lane attested). True only when every member and the judge were served under the attested class and each has a reference in attestation_refs. Signed in the top-level receipt." }, "attestation_simulated": { "type": "boolean", "description": "True when any attestation behind the council is a development report; a production router never accepts one." }, "attestation_refs": { "type": "array", "description": "One entry per call that took part, members in order and then the judge: what the router itself verified about the provider that served it. Signed in the top-level receipt.", "items": { "allOf": [ { "$ref": "#/components/schemas/AttestationRef" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "member", "judge" ] }, "label": { "type": "string", "description": "The member's label; absent for the judge." }, "receipt_id": { "type": "string", "description": "The receipt of that call." } } } ] } } }, "additionalProperties": true }, "AttestationRef": { "type": "object", "description": "The attestation the router had verified for a provider when it served a call: the hash of the attestation report and, when the provider attested through a self-signed TLS certificate, the pinned key the router's connection to it accepts. Recorded in the signed receipt of a call made under an attested council or attested dual verification, as payload.attestation_ref. Receipts made any other way do not carry it. The same data is at GET /api/v1/attestation/{providerId}.", "required": [ "provider", "report_hash", "tls_pin" ], "properties": { "provider": { "type": "string" }, "tee": { "type": [ "string", "null" ], "description": "tdx, snp, nvidia-cc, tinfoil or dev." }, "report_hash": { "type": "string", "description": "Hash of the attestation report the router verified (the payload.attestation field of the same receipt)." }, "attested_at": { "type": [ "string", "null" ], "format": "date-time" }, "tls_pin": { "type": [ "object", "null" ], "description": "Null when the provider did not attest through a self-signed certificate.", "properties": { "spki_sha256": { "type": "string", "description": "SHA-256 of the pinned certificate's SubjectPublicKeyInfo." }, "attestation_ref": { "type": [ "string", "null" ], "description": "SHA-256 of the quote the certificate names." } } }, "simulated": { "type": "boolean", "description": "true when the report is development evidence." } } }, "VerificationResult": { "type": "object", "description": "Present on verify \"dual\" responses. agree is true when both providers returned the same output (exactly, or after whitespace is collapsed); it says nothing about whether either provider is attested, unless the request used lane attested (then attested and attestation_refs say so). The response body is the first provider's output.", "properties": { "providers": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2 }, "agree": { "type": "boolean" }, "match": { "type": "string", "enum": [ "exact", "normalized", "none" ] }, "receipts": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2 }, "seed": { "type": "integer" }, "temperature": { "type": "number", "enum": [ 0 ] }, "quantizations": { "type": "array", "items": { "type": "string" } }, "attested": { "type": "boolean", "description": "Present only on lane attested. True when both calls were served by two different providers under the attested class and each has a reference in attestation_refs. Signed in both receipts, next to agree." }, "attestation_refs": { "type": "array", "description": "One entry per call that ran (label A or B), in the same order as receipts. Each receipt also carries its own provider's reference as payload.attestation_ref.", "items": { "allOf": [ { "$ref": "#/components/schemas/AttestationRef" }, { "type": "object", "properties": { "label": { "type": "string" }, "receipt_id": { "type": "string" } } } ] } } }, "additionalProperties": true }, "EmbeddingRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "minItems": 1, "maxItems": 2048, "items": { "type": "string" } } ] }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" } } }, "ProviderPreferences": { "type": "object", "description": "Provider routing preferences (order, only, ignore, sort, max_price, private and others) plus the disclosure options below.", "additionalProperties": true, "properties": { "disclosure": { "type": "string", "enum": [ "none", "policy", "any" ], "default": "any", "description": "Ceiling on how a prompt may be handled. none: only providers whose retention is declared attested and whose TEE attestation is fresh. policy: those, plus providers with a documented no-retention policy and no legal hold. any: no filter. Never silently relaxed: if nothing qualifies the request fails (409, or 503 when qualifying providers are down). A request with a ceiling never uses the response cache." }, "lane": { "type": "string", "enum": [ "public", "attested", "unlinkable" ], "default": "public", "description": "public: any endpoint; attested endpoints get attested_bonus (default 1.25) in the selection weight. attested: only endpoints with attested retention and a fresh, verified attestation, with no fallback to any other (503 no_attested_endpoint). unlinkable: the same endpoints, and only for a request that arrived through the Oblivious HTTP gateway by way of an independent relay (see Oblivious HTTP), or through the router's Tor onion service where it serves the lane that way, and is paid with a blind token; 501 where the router serves the lane on neither path, 403 lane_requires_anonymous_auth for an API key or a wallet, 403 unlinkable_requires_relay or unlinkable_requires_independent_relay, 401 unlinkable_requires_token otherwise. Unset: the key's default (routing.provider.lane), then the saved route's, then public; a request through an independent relay paid with a blind token defaults to unlinkable. provider.order, only and ignore still apply inside a lane. On attested and unlinkable the router still terminates TLS and sees the prompt; end-to-end encryption through the router is planned." }, "lane_downgrade": { "type": "string", "enum": [ "none", "attested" ], "default": "none", "description": "attested: a request for lane unlinkable that carries an API key or a wallet is served on lane attested instead of being refused with lane_requires_anonymous_auth. Never downgrades to public. Same as the X-Anyroute-Lane-Downgrade header; none in either refuses the downgrade." } } }, "DisclosureClaim": { "type": "object", "required": [ "source", "as_of" ], "properties": { "source": { "type": "string", "description": "The document or statement the value comes from." }, "as_of": { "type": "string", "format": "date", "description": "The date the source was checked." } } }, "DisclosureProfile": { "type": "object", "required": [ "provider", "declared", "retention", "jurisdiction", "legal_hold", "training_use", "claims", "current" ], "properties": { "provider": { "type": "string" }, "declared": { "type": "boolean", "description": "False when the operator has recorded nothing; every value is then the conservative default." }, "retention": { "type": "string", "enum": [ "attested", "policy", "logs" ], "description": "attested: the provider states prompts are not retained and runs in a TEE. policy: a documented no-retention policy. logs: prompts may be logged (default)." }, "jurisdiction": { "type": "string", "description": "Where the operator is subject to legal process; unknown by default." }, "legal_hold": { "type": "object", "properties": { "active": { "type": [ "boolean", "null" ], "description": "null = not declared. A no-retention policy is not trusted while a hold is active or undeclared." }, "note": { "type": [ "string", "null" ] } } }, "training_use": { "type": "string", "enum": [ "none", "opt_in", "yes", "unknown" ] }, "claims": { "type": "object", "description": "The source and date behind each value; null when the value is a default.", "properties": { "retention": { "oneOf": [ { "$ref": "#/components/schemas/DisclosureClaim" }, { "type": "null" } ] }, "jurisdiction": { "oneOf": [ { "$ref": "#/components/schemas/DisclosureClaim" }, { "type": "null" } ] }, "legal_hold": { "oneOf": [ { "$ref": "#/components/schemas/DisclosureClaim" }, { "type": "null" } ] }, "training_use": { "oneOf": [ { "$ref": "#/components/schemas/DisclosureClaim" }, { "type": "null" } ] } } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "current": { "type": "object", "properties": { "class": { "type": "string", "enum": [ "attested", "policy", "vendor-forwarded" ] }, "attestation_fresh": { "type": "boolean" }, "tee": { "type": [ "string", "null" ] }, "simulated": { "type": "boolean", "description": "True when the attestation behind an attested class is a development report." } } } } }, "DisclosureInput": { "type": "object", "additionalProperties": false, "description": "Every claim is optional and carries its own source and date.", "properties": { "retention": { "type": "object", "required": [ "value", "source", "as_of" ], "properties": { "value": { "type": "string", "enum": [ "attested", "policy", "logs" ] }, "source": { "type": "string" }, "as_of": { "type": "string", "format": "date" } } }, "jurisdiction": { "type": "object", "required": [ "value", "source", "as_of" ], "properties": { "value": { "type": "string", "minLength": 2, "maxLength": 64 }, "source": { "type": "string" }, "as_of": { "type": "string", "format": "date" } } }, "legal_hold": { "type": "object", "required": [ "active", "source", "as_of" ], "properties": { "active": { "type": "boolean" }, "note": { "type": "string", "maxLength": 500 }, "source": { "type": "string" }, "as_of": { "type": "string", "format": "date" } } }, "training_use": { "type": "object", "required": [ "value", "source", "as_of" ], "properties": { "value": { "type": "string", "enum": [ "none", "opt_in", "yes" ] }, "source": { "type": "string" }, "as_of": { "type": "string", "format": "date" } } } } }, "KeyCreateRequest": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "account", "inference", "read" ], "description": "E149: create only; scope is fixed. Explicit scope requires a management Bearer key. read cannot use management or team and can never spend or write." }, "project": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z0-9._-]{1,48}$", "description": "C134: PATCH only; set or clear a default project. POST rejects this field." }, "name": { "type": "string", "maxLength": 100 }, "limit": { "type": [ "number", "null" ], "minimum": 0, "description": "USD budget; alias of budget_usd." }, "budget_usd": { "type": [ "number", "null" ], "minimum": 0 }, "limit_reset": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", null ] }, "rpm": { "type": [ "integer", "null" ], "minimum": 1 }, "tpm": { "type": [ "integer", "null" ], "minimum": 1 }, "allowed_ips": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 32, "items": { "type": "string", "maxLength": 64 }, "description": "E148: PATCH only. Owner-set IPv4/IPv6 addresses or CIDRs; null removes the restriction. Key reads return null by default. A mismatch, onion or unlinkable request is refused before routing or charging with 403 ip_not_allowed. Caller IP is compared in memory and is not stored or logged by this feature." }, "allowed_models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "team": { "type": [ "string", "null" ], "description": "Applies to authenticated management-key creation." }, "pay_with_default": { "type": [ "string", "null" ], "maxLength": 16 }, "disabled": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "guardrails": { "type": [ "object", "null" ], "properties": { "pii": { "type": "string", "enum": [ "redact", "block" ] }, "deny_patterns": { "type": "array", "maxItems": 50, "items": { "type": "string" } }, "max_input_chars": { "type": "integer", "minimum": 1 }, "redact_output": { "type": "boolean" } } }, "routing": { "type": [ "object", "null" ], "additionalProperties": true }, "management": { "type": "boolean", "description": "Only honored for authorized authenticated sub-key creation; root-key management is never granted by this field." }, "tracing": { "oneOf": [ { "$ref": "#/components/schemas/TracingSettings" }, { "type": "null" } ], "description": "Trace export for this key's public-lane calls; null removes it." }, "role": { "type": "string", "enum": [ "admin", "dev", "member", "viewer", "agent" ], "description": "The new key's role in its team (default member). A key cannot hand out a role above its own. In a team with an org budget every key needs a limit that fits." }, "topup": { "oneOf": [ { "$ref": "#/components/schemas/KeyTopup" }, { "type": "null" } ], "description": "PATCH only. Auto top-up of this key's limit from the account's credits; null clears it. The key needs a limit without limit_reset." } }, "additionalProperties": false }, "KeyTopup": { "type": "object", "description": "When the key has less than below_usd of its limit left, the router raises the limit by add_usd, at most max_per_week_usd per UTC week (Monday to Sunday), and only while the account's available credits cover the key's remaining allowance after it. No money moves. It runs after a debit and when the key's limit would refuse a request. Each top-up, or skipped top-up with its reason, shows in Activity (kind topup) and the inbox. Rulebook caps still apply.", "required": [ "below_usd", "add_usd", "max_per_week_usd" ], "properties": { "below_usd": { "type": "number", "minimum": 0.01, "maximum": 1000 }, "add_usd": { "type": "number", "minimum": 0.01, "maximum": 1000, "description": "At most max_per_week_usd." }, "max_per_week_usd": { "type": "number", "minimum": 0.01, "maximum": 5000 } }, "additionalProperties": false }, "Key": { "type": "object", "required": [ "hash", "name", "disabled", "created_at" ], "properties": { "scope": { "type": "string", "enum": [ "account", "inference", "read" ], "description": "E149: read permits owner account visibility only on the explicit GET allow-list; all other paths and methods return 403 read_only_key." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "C127: The key’s expiry, or null for no expiry. Expired credentials are refused with HTTP 401 key_expired; stored disabled is independent." }, "hash": { "type": "string" }, "name": { "type": "string" }, "disabled": { "type": "boolean" }, "limit": { "type": [ "number", "null" ] }, "usage": { "type": "number" }, "allowed_ips": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 32, "items": { "type": "string", "maxLength": 64 }, "description": "E148: PATCH only. Owner-set IPv4/IPv6 addresses or CIDRs; null removes the restriction. Key reads return null by default. A mismatch, onion or unlinkable request is refused before routing or charging with 403 ip_not_allowed. Caller IP is compared in memory and is not stored or logged by this feature." }, "allowed_models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "last_used": { "type": [ "string", "null" ], "format": "date-time" }, "tracing": { "oneOf": [ { "$ref": "#/components/schemas/Tracing" }, { "type": "null" } ] }, "topup": { "oneOf": [ { "$ref": "#/components/schemas/KeyTopup" }, { "type": "null" } ] }, "topups_this_week_usd": { "type": "number", "description": "GET /api/v1/keys/{hash} and PATCH: the auto top-ups added to this key's limit since Monday 00:00 UTC." }, "project": { "type": "string", "description": "C134: lowercased default project label; omitted when unset." } } }, "GenerationSummary": { "type": "object", "required": [ "id", "created_at", "model", "total_cost" ], "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "model": { "type": "string" }, "provider_name": { "type": "string" }, "tokens_prompt": { "type": "integer" }, "tokens_completion": { "type": "integer" }, "total_cost": { "type": "number" }, "streamed": { "type": "boolean" }, "cancelled": { "type": "boolean" } } }, "ReceiptKeys": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "required": [ "kty", "crv", "x", "kid" ], "properties": { "kty": { "const": "OKP" }, "crv": { "const": "Ed25519" }, "x": { "type": "string", "description": "The raw 32-byte public key, base64url." }, "kid": { "type": "string", "description": "First 16 hex characters of SHA-256 of the raw key." }, "use": { "const": "sig" }, "alg": { "const": "EdDSA" }, "valid_from": { "type": "string", "format": "date-time" }, "retired_at": { "type": [ "string", "null" ], "format": "date-time" }, "onchain_tx": { "type": [ "string", "null" ] } } } } } }, "AttestationSummary": { "type": "object", "required": [ "generated_at", "attestation_interval_ms", "fresh_within_ms", "history_days", "providers" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "attestation_interval_ms": { "type": "integer" }, "fresh_within_ms": { "type": "integer", "description": "How old a verified attestation may be and still count as fresh." }, "history_days": { "type": "integer" }, "providers": { "type": "array", "items": { "type": "object", "required": [ "provider", "name", "status", "fresh" ], "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "attested", "simulated", "unverified" ] }, "reason": { "type": "string", "description": "Present when status is unverified." }, "tee": { "type": [ "string", "null" ] }, "attested_at": { "type": [ "string", "null" ], "format": "date-time" }, "history_since": { "type": [ "string", "null" ], "format": "date-time", "description": "The first recorded attestor run." }, "runs_7d": { "type": "object", "properties": { "total": { "type": "integer" }, "attested": { "type": "integer", "description": "Runs that passed with hardware evidence (simulated evidence is not counted)." }, "attested_pct": { "type": [ "number", "null" ] } } }, "fresh": { "type": "object", "required": [ "24h", "7d" ], "properties": { "24h": { "type": "object", "required": [ "share", "observed_ms", "observed_from", "history_complete", "buckets" ], "properties": { "share": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Covered part of the time the record spans within the window; null when nothing is recorded." }, "observed_ms": { "type": "integer", "description": "How much of the window the record spans." }, "observed_from": { "type": [ "string", "null" ], "format": "date-time" }, "history_complete": { "type": "boolean", "description": "False when the record does not reach back to the start of the window; the earlier time is unknown, not covered and not uncovered." }, "buckets": { "type": "array", "items": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "description": "Equal slices from the start of the window to now (48 for 24h, 84 for 7d): percent covered, or null before the record begins." } } }, "7d": { "type": "object", "required": [ "share", "observed_ms", "observed_from", "history_complete", "buckets" ], "properties": { "share": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Covered part of the time the record spans within the window; null when nothing is recorded." }, "observed_ms": { "type": "integer", "description": "How much of the window the record spans." }, "observed_from": { "type": [ "string", "null" ], "format": "date-time" }, "history_complete": { "type": "boolean", "description": "False when the record does not reach back to the start of the window; the earlier time is unknown, not covered and not uncovered." }, "buckets": { "type": "array", "items": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "description": "Equal slices from the start of the window to now (48 for 24h, 84 for 7d): percent covered, or null before the record begins." } } } } }, "measurement": { "type": [ "object", "null" ], "properties": { "digests": { "type": [ "object", "null" ], "description": "Digests only: image_digest, compose_hash, model_digest, mrtd, rtmr0 to rtmr3, measurement.", "additionalProperties": { "type": "string" } } } }, "measurement_changes_7d": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "changed": { "type": "array", "items": { "type": "string" } } } } }, "last_measurement_change": { "type": [ "object", "null" ], "properties": { "at": { "type": "string", "format": "date-time" }, "changed": { "type": "array", "items": { "type": "string" } }, "from": { "type": [ "object", "null" ], "description": "Digests only: image_digest, compose_hash, model_digest, mrtd, rtmr0 to rtmr3, measurement.", "additionalProperties": { "type": "string" } }, "to": { "type": [ "object", "null" ], "description": "Digests only: image_digest, compose_hash, model_digest, mrtd, rtmr0 to rtmr3, measurement.", "additionalProperties": { "type": "string" } } } }, "last_failure": { "type": [ "object", "null" ], "properties": { "at": { "type": "string", "format": "date-time" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "probe": { "type": [ "object", "null" ], "description": "The latest health-probe outcome and when it began.", "properties": { "ok": { "type": "boolean" }, "since": { "type": "string", "format": "date-time" }, "reason": { "type": [ "object", "null" ], "description": "A code from a fixed list with its message; never the provider's own text.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "canary": { "type": [ "object", "null" ], "properties": { "ok": { "type": "boolean" }, "at": { "type": "string", "format": "date-time" }, "model": { "type": [ "string", "null" ] }, "reason": { "type": [ "object", "null" ], "description": "A code from a fixed list with its message; never the provider's own text.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "AttestationEvent": { "type": "object", "required": [ "id", "kind", "at", "ok" ], "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "attestation", "canary", "probe" ] }, "at": { "type": "string", "format": "date-time" }, "ok": { "type": "boolean" }, "reason": { "type": [ "object", "null" ], "description": "A code from a fixed list with its message; never the provider's own text.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "tee": { "type": [ "string", "null" ] }, "simulated": { "type": "boolean", "description": "Development evidence: never counted as a fresh attestation." }, "attestation_hash": { "type": [ "string", "null" ] }, "tls_spki_sha256": { "type": [ "string", "null" ], "description": "SPKI hash of the certificate the connection was pinned to, when it was." }, "measurements": { "type": [ "object", "null" ], "description": "Digests only: image_digest, compose_hash, model_digest, mrtd, rtmr0 to rtmr3, measurement.", "additionalProperties": { "type": "string" } }, "measurement_changed": { "type": "boolean", "description": "The run's digests differ from the previous accepted run's, comparing the fields both report." }, "verifiers": { "type": "array", "items": { "type": "string" } }, "detail": { "type": [ "object", "null" ], "additionalProperties": true } } }, "AttestationHistory": { "type": "object", "required": [ "provider", "history_days", "data", "next" ], "properties": { "provider": { "type": "string" }, "history_days": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttestationEvent" } }, "next": { "type": [ "string", "null" ], "description": "Pass as before for the next page; null on the last page." } } }, "ProviderAttestation": { "type": "object", "required": [ "provider", "status", "checks", "not_checked" ], "properties": { "provider": { "type": "string" }, "status": { "type": "string", "enum": [ "attested", "simulated", "unverified" ] }, "reason": { "type": "string", "enum": [ "no_attestation", "last_attempt_failed", "simulated_evidence_refused", "attestation_stale" ], "description": "Present when status is unverified." }, "tee": { "type": [ "string", "null" ] }, "attested_at": { "type": [ "string", "null" ], "format": "date-time" }, "attestation_hash": { "type": [ "string", "null" ] }, "verifiers": { "type": "array", "items": { "type": "string" }, "description": "The verifiers that accepted the quote; empty unless status is attested." }, "policy_hash": { "type": [ "string", "null" ], "description": "The classifier policy hash this fresh attestation bound (the value sent as X-Anyroute-Policy-Hash); null unless status is attested and one was bound." }, "measurement": { "type": [ "object", "null" ], "description": "Last recorded digests (image_digest, compose_hash, model_digest), status, attested_now, registers { mrtd, rtmr3 } of the recorded quote, transparency_log { found, inclusion_verified, checkpoint_signature_verified, subject (measurement_bundle or image_digest), entry_url, bundle, ... } and registry { address, state, tx_hash, registered_at }.", "additionalProperties": true }, "checks": { "type": "object", "required": [ "quote_verified", "digests_bound_to_quote", "transparency_log_entry", "transparency_log_checkpoint_signature", "registered_on_chain" ], "additionalProperties": { "type": "boolean" } }, "not_checked": { "type": "array", "items": { "type": "string" } } } }, "RouteExplanation": { "type": "object", "additionalProperties": false, "description": "Versioned additive router statement, not an independent selection proof. eligible counts final-plan candidate offers before attempt limits for the serving model; skipped counts its exclusions. Fallback error classes cover earlier attempts, including earlier models, without raw errors or provider identities. No URLs, keys, addresses, content or weights. Both receipt signatures cover route.", "required": [ "v", "provider", "reason", "eligible", "skipped", "lane", "parameters", "network_host" ], "properties": { "v": { "type": "integer", "const": 1 }, "provider": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,96}$" }, "reason": { "type": "string", "enum": [ "lowest_price", "lowest_latency", "highest_throughput", "weighted_choice", "provider_order", "preferred_performance", "byok_priority", "only_eligible", "only_parameter_support", "fallback" ] }, "eligible": { "type": "integer", "minimum": 1 }, "skipped": { "type": "object", "additionalProperties": false, "properties": { "health": { "type": "integer", "minimum": 1 }, "lane": { "type": "integer", "minimum": 1 }, "disclosure": { "type": "integer", "minimum": 1 }, "attestation": { "type": "integer", "minimum": 1 }, "parameters": { "type": "integer", "minimum": 1 }, "price": { "type": "integer", "minimum": 1 }, "context": { "type": "integer", "minimum": 1 }, "preferences": { "type": "integer", "minimum": 1 }, "availability": { "type": "integer", "minimum": 1 }, "other": { "type": "integer", "minimum": 1 } } }, "lane": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] }, "parameters": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "tools", "tool_choice", "response_format", "temperature", "seed", "max_tokens", "stop", "top_p", "top_k", "reasoning", "include_reasoning", "modalities", "audio" ] } }, "network_host": { "type": "boolean" }, "fallback": { "type": "object", "additionalProperties": false, "properties": { "http_5xx": { "type": "integer", "minimum": 1 }, "timeout": { "type": "integer", "minimum": 1 }, "connection": { "type": "integer", "minimum": 1 }, "rate_limited": { "type": "integer", "minimum": 1 }, "provider_auth": { "type": "integer", "minimum": 1 }, "rejected": { "type": "integer", "minimum": 1 }, "empty200": { "type": "integer", "minimum": 1 }, "unreadable": { "type": "integer", "minimum": 1 }, "interrupted": { "type": "integer", "minimum": 1 }, "other": { "type": "integer", "minimum": 1 } } } } }, "Receipt": { "type": "object", "properties": { "structured_output": { "$ref": "#/components/schemas/StructuredOutputResult" }, "id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true, "properties": { "route": { "$ref": "#/components/schemas/RouteExplanation" }, "decision_tag": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The caller's X-Anyroute-Decision-Tag, when DECISION_TAGS_ENABLED is true." } }, "description": "Signed fields. Optional route is a versioned additive claim when ROUTE_EXPLAIN_ENABLED is true (default false). Optional decision_tag is the caller-computed digest sent as X-Anyroute-Decision-Tag (DECISION_TAGS_ENABLED, default false). Among them, disclosure (attested, policy or vendor-forwarded) and lane (public, attested or unlinkable) record how the call was served; attestation_simulated is true when the attestation behind an attested call is a development report. attestation_ref (see AttestationRef) is present on calls made under an attested council or attested dual verification. For a call paid with a blind token, payer is null and nullifier (the SHA-256 of the spent token) and token_key_id are present; nothing names an account. Receipts issued before these fields existed do not carry them." }, "sig": { "type": "string" }, "key_id": { "type": "string" }, "leaf": { "type": [ "string", "null" ] }, "anchor": { "type": [ "object", "null" ] }, "version": { "type": "integer", "enum": [ 1, 2 ] }, "v2": { "oneOf": [ { "$ref": "#/components/schemas/ReceiptV2" }, { "type": "null" } ] }, "privacy": { "$ref": "#/components/schemas/PrivacyLabel", "description": "The privacy label derived from payload for readers. It is not part of what is signed." } } }, "ReceiptV2": { "type": "object", "description": "Receipt v2 (spec 0004 Section 4): a COSE_Sign1 over deterministic CBOR claims, signed EdDSA with the same key as v1 (kid is the key id's 8 bytes). claims is the JSON view of exactly what cose signs. Token counts are bucketed; nothing names a payer, an address or content.", "properties": { "alg": { "type": "string", "const": "EdDSA" }, "kid": { "type": "string" }, "content_type": { "type": "string" }, "cose": { "type": "string", "contentEncoding": "base64" }, "leaf": { "type": "string", "description": "keccak256(keccak256(COSE bytes))." }, "anchor": { "type": [ "object", "null" ] }, "claims": { "$ref": "#/components/schemas/ReceiptClaimsV2" } } }, "ReceiptClaimsV2": { "type": "object", "properties": { "route": { "$ref": "#/components/schemas/RouteExplanation" }, "decision_tag": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Optional: the caller's X-Anyroute-Decision-Tag (DECISION_TAGS_ENABLED)." }, "v": { "type": "integer", "const": 2 }, "rid": { "type": "string" }, "iat": { "type": "integer" }, "iss": { "type": "string" }, "model": { "type": "object", "properties": { "id": { "type": "string" } } }, "node": { "type": "object", "properties": { "provider": { "type": "string" }, "quote_ref": { "type": "string" }, "policy_hash": { "type": "string" } } }, "req": { "type": "object", "properties": { "h": { "type": "string" }, "n_in_bucket": { "type": "string", "examples": [ "512-1024" ] } } }, "resp": { "type": "object", "properties": { "h": { "type": "string" }, "chain": { "type": "string", "description": "Streams only: the chunk hash chain head." }, "n_out_bucket": { "type": "string" }, "finish": { "type": "string" }, "stream": { "type": "boolean" }, "complete": { "type": "boolean" } } }, "lane": { "type": "string" }, "disclosure": { "type": "string" }, "policy": { "type": "object", "description": "Present only when the serving endpoint's fresh attestation bound a classifier policy.", "properties": { "enforced": { "type": "boolean" }, "blocked": { "type": "boolean" } } }, "credit": { "type": "object", "properties": { "mode": { "type": "string" }, "cost_units": { "type": "integer", "description": "Amount charged in millionths of a US dollar, rounded up." }, "keyset": { "type": "string" } } } } }, "ReceiptProof": { "type": "object", "properties": { "rid": { "type": "string" }, "leaf": { "type": [ "string", "null" ] }, "leaf_version": { "type": "integer", "enum": [ 1, 2 ] }, "rooted": { "type": "boolean" }, "anchored": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "local", "confirmed" ] }, "root": { "type": "string" }, "anchor_index": { "type": "integer" }, "leaf_index": { "type": "integer" }, "proof": { "type": "array", "items": { "type": "string" } }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "tx": { "type": [ "string", "null" ] }, "chain": { "type": "integer" }, "contract": { "type": [ "string", "null" ] } } }, "HostAnchorProof": { "type": "object", "required": [ "leaf", "rooted", "anchored", "status", "provider", "provider_id_hash", "attestation_ref", "receipt_key", "root", "leaf_index", "proof" ], "properties": { "rid": { "type": "string", "description": "The receipt id the sidecar gave it." }, "leaf": { "type": "string" }, "rooted": { "type": "boolean", "const": true }, "anchored": { "type": "boolean", "description": "True only when the root was posted on chain and confirmed." }, "status": { "type": "string", "enum": [ "pending", "local", "confirmed" ], "description": "confirmed: on chain; pending: to be posted (the chain was unreachable); local: kept off chain because no chain is configured." }, "provider": { "type": "string" }, "provider_id_hash": { "type": "string", "description": "keccak256 of the provider id's bytes: the providerId the root is posted under." }, "attestation_ref": { "type": "string", "description": "64 hex: SHA-256 of the boot quote the router verified, which every leaf in the root names." }, "receipt_key": { "type": "object", "description": "The receipt key the quote binds; every leaf in the root verified under it.", "properties": { "key_id": { "type": "string" }, "public_key": { "type": "string", "description": "Raw Ed25519 public key, hex." } } }, "root_id": { "type": "integer" }, "root": { "type": "string" }, "leaf_index": { "type": "integer" }, "proof": { "type": "array", "items": { "type": "string" }, "description": "OpenZeppelin MerkleProof-compatible path (sorted-pair keccak256)." }, "count": { "type": "integer" }, "window": { "type": "object", "description": "When the router collected the root's leaves: [from, to).", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "anchor_index": { "type": [ "integer", "null" ], "description": "Index in ReceiptAnchor.attestedAnchors once posted." }, "tx": { "type": [ "string", "null" ] }, "block": { "type": [ "integer", "null" ] }, "chain": { "type": "integer" }, "contract": { "type": [ "string", "null" ] } } }, "ReceiptV2VerificationRequest": { "type": "object", "required": [ "cose" ], "properties": { "cose": { "type": "string", "contentEncoding": "base64" }, "request_sha256": { "type": "string" }, "response_sha256": { "type": "string" }, "chunks": { "type": "array", "items": { "type": "string" } }, "anchor": { "type": "object", "required": [ "root", "proof" ], "properties": { "root": { "type": "string" }, "proof": { "type": "array", "items": { "type": "string" } }, "index": { "type": "integer" } } }, "decision_tag": { "type": "string", "pattern": "^(sha256:)?[0-9a-fA-F]{64}$", "description": "Optional: the SHA-256 of your order, computed on your side as the decision-receipt helpers do (canonical JSON, sha256:<64 hex>). The result reports decision_tag (the tag the receipt's signed contents carry, or null) and decision_tag_valid (whether it equals this value; null when omitted), and valid is false when they differ. Only the hash is sent." } } }, "ReceiptVerificationRequest": { "type": "object", "required": [ "payload", "sig", "key_id" ], "properties": { "payload": { "type": "object", "additionalProperties": true }, "sig": { "type": "string" }, "key_id": { "type": "string" }, "anchor": { "type": "object", "required": [ "root", "proof" ], "properties": { "root": { "type": "string" }, "proof": { "type": "array", "items": { "type": "string" } }, "index": { "type": "integer" } } }, "decision_tag": { "type": "string", "pattern": "^(sha256:)?[0-9a-fA-F]{64}$", "description": "Optional: the SHA-256 of your order, computed on your side as the decision-receipt helpers do (canonical JSON, sha256:<64 hex>). The result reports decision_tag (the tag the receipt's signed contents carry, or null) and decision_tag_valid (whether it equals this value; null when omitted), and valid is false when they differ. Only the hash is sent." } } }, "SavedRouteConfig": { "type": "object", "additionalProperties": false, "required": [ "models" ], "properties": { "models": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "string" }, "description": "Catalog model ids in fallback order; no nested @route/." }, "provider": { "type": [ "object", "null" ], "description": "Provider preferences: order, only, ignore, allow_fallbacks, sort (price|latency|throughput), data_collection, zdr, require_parameters, max_price, and the privacy settings lane (public|attested) and disclosure (none|policy|any). For lane and disclosure the stricter of the route and the request applies, so a request can tighten a route but never loosen it; a route on the attested lane is served only by attested providers or refused. lane attested already implies disclosure none." }, "params": { "type": [ "object", "null" ], "description": "Default request parameters from a closed whitelist (temperature, top_p, top_k, min_p, top_a, frequency_penalty, presence_penalty, repetition_penalty, max_tokens, seed, stop, reasoning, verbosity). Prompt fields are rejected." } } }, "SavedRoute": { "type": "object", "required": [ "id", "slug", "model", "name", "config" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" }, "model": { "type": "string", "description": "Use as the request model, e.g. @route/my-coder." }, "name": { "type": "string" }, "description": { "type": "string" }, "config": { "$ref": "#/components/schemas/SavedRouteConfig" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SavedRouteInput": { "type": "object", "additionalProperties": false, "properties": { "slug": { "type": "string" }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 280 }, "config": { "$ref": "#/components/schemas/SavedRouteConfig" } } }, "AgentSession": { "type": "object", "required": [ "id", "status", "expires_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "ended", "expired", "budget_exhausted" ] }, "key_label": { "type": "string" }, "key_hash": { "type": "string" }, "budget_usd": { "type": "number" }, "spent_usd": { "type": "number" }, "reserved_usd": { "type": "number" }, "remaining_usd": { "type": "number" }, "calls": { "type": "integer" }, "last_call_at": { "type": [ "string", "null" ] }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": [ "object", "null" ] }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "time_left_s": { "type": "integer" }, "ended_at": { "type": [ "string", "null" ] }, "end_reason": { "type": [ "string", "null" ] } } }, "AgentSessionCreate": { "type": "object", "additionalProperties": false, "required": [ "budget_usd" ], "properties": { "name": { "type": "string", "maxLength": 80 }, "budget_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "ttl_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 60 }, "allowed_models": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "Catalog ids or @route/; must be within the creator's allowlist." }, "metadata": { "type": "object", "description": "Labels only, at most 2 KB; prompt-like keys are refused." } } }, "SpendReport": { "type": "object", "description": "Spend for the caller's scope (a management key sees its account; other keys see themselves). UTC calendar.", "properties": { "scope": { "type": "string" }, "period": { "type": "string" }, "group_by": { "type": "string" }, "totals": { "type": "object" }, "anomaly": { "type": "object" }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "cost_usd": { "type": "number" }, "requests": { "type": "integer" } } } }, "breakdown": { "type": "array", "items": { "type": "object" } }, "budgets": { "type": "array", "items": { "type": "object" } } } }, "SpendAlert": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "threshold", "budget_pct", "anomaly" ] }, "window": { "type": "string", "enum": [ "day", "week", "month" ] }, "key_hash": { "type": [ "string", "null" ] }, "threshold_usd": { "type": [ "number", "null" ] }, "pct": { "type": [ "integer", "null" ] }, "multiplier": { "type": [ "number", "null" ] }, "webhook_url": { "type": [ "string", "null" ], "description": "Masked as https://host/…" }, "enabled": { "type": "boolean" }, "last_fired_at": { "type": [ "string", "null" ] }, "history": { "type": "array", "items": { "type": "object" } } } }, "HolderTier": { "type": "object", "required": [ "name", "min", "rpm_multiplier", "discount_bps" ], "properties": { "name": { "type": "string" }, "min": { "type": "string", "description": "Minimum balance in whole tokens (decimal string)." }, "rpm_multiplier": { "type": "number", "minimum": 1, "description": "Multiplies the key's rpm and tpm limits." }, "discount_bps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Lowers Anyroute's own fee rates by this many basis points, never below 0." } } }, "BlindKeys": { "type": "object", "required": [ "token_type", "scheme", "challenge", "challenge_digest", "keys" ], "properties": { "token_type": { "const": 2 }, "scheme": { "const": "RSABSSA-SHA384-PSS-Deterministic" }, "modulus_bits": { "type": "integer" }, "issuer_name": { "type": "string" }, "challenge": { "type": "string", "description": "The TokenChallenge (RFC 9577), base64url." }, "challenge_digest": { "type": "string", "description": "SHA-256 of the challenge, hex; the challenge_digest field of every token." }, "unit_price_usd": { "type": "string", "description": "USD per token-unit for keys created from now on; each key states its own value_usd." }, "epoch_seconds": { "type": "integer" }, "redeem_grace_seconds": { "type": "integer" }, "max_batch": { "type": "integer" }, "epoch": { "type": "integer" }, "now": { "type": "string", "format": "date-time" }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/BlindKey" } }, "commitments": { "type": "array", "items": { "type": "object", "properties": { "epoch": { "type": "integer" }, "commitment": { "type": "string", "description": "keccak256(abi.encode(uint64 epoch, uint32[] denominations, bytes32[] keyIds)), as recorded by BlindIssuer.commitEpoch." } } } } } }, "BlindKey": { "type": "object", "required": [ "token_key_id", "token_key", "epoch", "denomination", "status" ], "properties": { "token_key_id": { "type": "string", "description": "SHA-256 of the SubjectPublicKeyInfo, hex." }, "token_key": { "type": "string", "description": "RFC 9578 SubjectPublicKeyInfo (RSASSA-PSS, SHA-384, 48-byte salt), base64url." }, "epoch": { "type": "integer" }, "denomination": { "enum": [ 1000, 10000, 100000 ], "description": "Token-units one token is worth." }, "value_usd": { "type": "string", "description": "What one token of this key is worth; fixed for the key's life." }, "unit_price_usd": { "type": "string" }, "status": { "enum": [ "upcoming", "issuing", "redeem_only", "expired", "revoked" ] }, "not_before": { "type": "string", "format": "date-time" }, "issue_until": { "type": "string", "format": "date-time" }, "redeem_until": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "issued": { "type": "integer", "description": "Tokens signed with this key (a count)." }, "redeemed": { "type": "integer", "description": "Tokens spent (a count)." } } }, "OhttpKeyList": { "type": "object", "required": [ "data", "signature" ], "properties": { "data": { "type": "object", "required": [ "v", "kind", "keys", "log", "relays" ], "properties": { "v": { "type": "integer", "const": 1 }, "kind": { "type": "string", "const": "ohttp-key-list" }, "issued": { "type": "string", "format": "date-time" }, "router": { "type": "string" }, "gateway": { "type": "object", "properties": { "url": { "type": "string" }, "keys_url": { "type": "string" }, "media_type": { "type": "string" } } }, "suites": { "type": "array", "items": { "type": "object", "properties": { "kem": { "type": "string" }, "kem_id": { "type": "integer" }, "kdf": { "type": "string" }, "kdf_id": { "type": "integer" }, "aead": { "type": "string" }, "aead_id": { "type": "integer" } } } }, "epoch_seconds": { "type": "integer" }, "grace_seconds": { "type": "integer" }, "keys": { "type": "array", "description": "Oldest first; at most the latest 512.", "items": { "type": "object", "properties": { "epoch": { "type": "integer" }, "key_id": { "type": "integer", "minimum": 0, "maximum": 255, "description": "The 8-bit key identifier: the epoch modulo 256." }, "kem_id": { "type": "integer" }, "public_key": { "type": "string", "description": "Raw X25519 public key, base64url." }, "config": { "type": "string", "description": "The key configuration (RFC 9458 section 3.1), base64url." }, "config_sha256": { "type": "string" }, "status": { "type": "string", "enum": [ "upcoming", "current", "grace", "expired", "revoked" ] }, "valid_from": { "type": "string", "format": "date-time" }, "accept_until": { "type": "string", "format": "date-time" }, "private_key_destroyed": { "type": "boolean" }, "entry_hash": { "type": "string", "description": "SHA-256 chain: this entry committed to the one before it." } } } }, "log": { "type": "object", "properties": { "algorithm": { "type": "string", "const": "sha256-chain" }, "entries": { "type": "integer", "description": "Keys ever created." }, "head": { "type": "string" }, "first_prev": { "type": "string", "description": "The entry hash before the first key listed (64 zeros when the list starts at the first key ever)." } } }, "relays": { "type": "array", "items": { "$ref": "#/components/schemas/Relay" } } } }, "signature": { "type": "object", "properties": { "alg": { "type": "string", "const": "Ed25519" }, "key_id": { "type": "string", "description": "A receipt signing key; see GET /api/v1/receipts/keys." }, "sig": { "type": "string", "description": "Base64 Ed25519 signature over the canonical JSON of data." } } } } }, "Relay": { "type": "object", "required": [ "operator", "url", "key_id", "independent" ], "properties": { "operator": { "type": "string" }, "url": { "type": "string", "description": "Where a client sends message/ohttp-req." }, "key_id": { "type": "string", "description": "Identifier of the credential this relay presents to the gateway." }, "independent": { "type": "boolean", "description": "False when the relay's operator is the gateway's own operator." } } }, "RelayList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "lane": { "type": "string", "const": "unlinkable" }, "gateway": { "type": "object", "properties": { "operator": { "type": "string" }, "url": { "type": "string" }, "keys_url": { "type": "string" }, "key_list_url": { "type": "string" }, "chunked": { "type": "object", "description": "Present only where the gateway accepts chunked Oblivious HTTP.", "properties": { "request": { "type": "string", "const": "message/ohttp-chunked-req" }, "response": { "type": "string", "const": "message/ohttp-chunked-res" } } } } }, "relays": { "type": "array", "items": { "$ref": "#/components/schemas/Relay" } }, "independent_operators": { "type": "integer", "description": "Distinct operators of independent relays." }, "note": { "type": "string" } } } } }, "BlindPurchaseRequest": { "type": "object", "additionalProperties": false, "required": [ "token_key_id", "blinded_msgs" ], "properties": { "token_key_id": { "type": "string", "description": "A key whose status is issuing." }, "blinded_msgs": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "256 bytes, base64url: the blinded token input, below the key's modulus." }, "description": "Distinct blinded messages, at most max_batch." } } }, "BlindPurchase": { "type": "object", "required": [ "token_key_id", "epoch", "denomination", "count", "cost_usd", "signatures" ], "properties": { "token_key_id": { "type": "string" }, "epoch": { "type": "integer" }, "denomination": { "type": "integer" }, "count": { "type": "integer" }, "cost_usd": { "type": "string" }, "replayed": { "type": "boolean", "description": "True when this exact purchase had already been made; nothing was charged again." }, "signatures": { "type": "array", "items": { "type": "string" }, "description": "signatures[i] answers blinded_msgs[i]; 256 bytes each, base64url." } } }, "HolderStatus": { "type": "object", "required": [ "enabled", "token", "wallet", "balance", "tier", "perks", "tiers", "credits_received" ], "properties": { "enabled": { "type": "boolean", "description": "Whether holder tiers apply to requests on this router." }, "token": { "type": [ "object", "null" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" } } }, "wallet": { "type": [ "string", "null" ], "description": "The wallet behind this key (wallet sign-in keys only)." }, "balance": { "type": [ "string", "null" ], "description": "Token balance in whole tokens (decimal string)." }, "balance_error": { "type": "boolean", "description": "True when the balance could not be read; no tier applies until it can." }, "tier": { "oneOf": [ { "$ref": "#/components/schemas/HolderTier" }, { "type": "null" } ] }, "next_tier": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "min": { "type": "string" }, "remaining": { "type": "string", "description": "Tokens still needed." } } }, "perks": { "type": [ "object", "null" ], "properties": { "rpm_multiplier": { "type": "number" }, "rpm": { "type": "integer", "description": "This key's request limit per minute with the multiplier (0 = unlimited)." }, "tpm": { "type": [ "integer", "null" ] }, "discount_bps": { "type": "integer" }, "fees": { "type": "object", "properties": { "prepaid_bps": { "type": "integer" }, "per_call_margin_bps": { "type": "integer" }, "byok_fee_bps": { "type": "integer" } } }, "note": { "type": "string" } } }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/HolderTier" } }, "credits_received": { "type": "array", "items": { "type": "object", "required": [ "period", "usd", "at" ], "properties": { "period": { "type": "string" }, "usd": { "type": "number" }, "at": { "type": "string", "format": "date-time" } } }, "description": "Free inference credits paid to this wallet, newest first. They pay for inference only and are not withdrawable." }, "credits_total_usd": { "type": "number" }, "hint": { "type": "string" } } }, "ModelLaneInput": { "type": "object", "additionalProperties": false, "required": [ "variant" ], "description": "A model's lane record. native_low_refusal and abliterated need license and base_model.", "properties": { "variant": { "type": "string", "enum": [ "mainstream", "native_low_refusal", "abliterated" ] }, "status": { "type": "string", "enum": [ "servable", "candidate" ], "default": "servable", "description": "candidate routes the model to no provider." }, "base_model": { "type": [ "string", "null" ], "maxLength": 200 }, "license": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[\\w.+-]+$", "description": "License identifier such as apache-2.0." }, "weights": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "source": { "type": [ "string", "null" ], "maxLength": 200, "description": "For example huggingface:owner/repo. A creator claim is checked against this repository." }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{7,64}$" }, "digest": { "type": [ "string", "null" ], "pattern": "^sha256:[0-9a-fA-F]{64}$" } } }, "creator_handle": { "type": [ "string", "null" ], "description": "Hugging Face handle of the uploader." } } }, "LaneCandidate": { "type": "object", "properties": { "id": { "type": "integer" }, "hugging_face_id": { "type": "string" }, "base_model": { "type": "string" }, "revision": { "type": [ "string", "null" ], "description": "The revision seen at discovery; the one evaluated." }, "license": { "type": [ "string", "null" ] }, "variant": { "type": "string", "enum": [ "abliterated", "native_low_refusal" ] }, "creator_handle": { "type": "string" }, "status": { "type": "string", "enum": [ "discovered", "rejected", "evaluated", "failed", "approved", "servable" ] }, "reason": { "type": [ "string", "null" ], "description": "Why a candidate was rejected or failed." }, "model": { "type": [ "string", "null" ], "description": "The catalog model that serves it, once linked." }, "provider": { "type": [ "string", "null" ] }, "discovered_at": { "type": "string", "format": "date-time" }, "approved_by": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "servable_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_evaluation": { "type": [ "object", "null" ], "properties": { "at": { "type": "string", "format": "date-time" }, "passed": { "type": "boolean" }, "refusal_rate": { "type": [ "number", "null" ], "description": "Share of the benign probe prompts the endpoint refused." }, "capability_score": { "type": [ "number", "null" ], "description": "Share of the exact-check prompts answered correctly." }, "canary_accuracy": { "type": [ "number", "null" ] }, "canary_quant_match": { "type": [ "boolean", "null" ] }, "detail": { "type": "object", "additionalProperties": true } } } } }, "CreatorClaim": { "type": "object", "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "hugging_face_id": { "type": "string" }, "handle": { "type": "string", "description": "Owner of the repository, from its id." }, "address": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "verified" ] }, "challenge": { "type": "string" }, "file": { "type": "string", "description": "File name to commit to the main branch of the repository." }, "file_content": { "type": "string", "description": "What the file must contain: the challenge on its own line." }, "expires_at": { "type": "string", "format": "date-time" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "onchain_tx": { "type": [ "string", "null" ] }, "royalty_bps": { "type": "integer" }, "expired": { "type": "boolean" }, "already_verified": { "type": "boolean" } } }, "SpendAlertInput": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "threshold", "budget_pct", "anomaly" ] }, "window": { "type": "string", "enum": [ "day", "week", "month" ] }, "threshold_usd": { "type": "number" }, "pct": { "type": "integer", "minimum": 1, "maximum": 1000 }, "multiplier": { "type": "number" }, "key_hash": { "type": "string" }, "webhook_url": { "type": [ "string", "null" ], "description": "HTTPS, public address only; stored encrypted." }, "enabled": { "type": "boolean" } } }, "AnthropicMessagesRequest": { "type": "object", "required": [ "model", "max_tokens", "messages" ], "properties": { "model": { "type": "string", "description": "A model id from GET /v1/models, or a name the operator mapped with ANTHROPIC_MODEL_MAP." }, "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", "description": "A content block: text, image (source base64 or url), tool_use, tool_result, document (text source only); thinking blocks are dropped.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image", "tool_use", "tool_result", "document", "thinking", "redacted_thinking" ] } }, "additionalProperties": true } } ] } } } }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string" } }, "additionalProperties": true } } ] }, "tools": { "type": "array", "description": "Custom tools (name, description, input_schema). Tools hosted by Anthropic are left out and named in X-Anyroute-Ignored.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": { "type": "object" } }, "additionalProperties": true } }, "tool_choice": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "auto", "any", "tool", "none" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } } }, "thinking": { "type": "object", "description": "Accepted and not acted on.", "additionalProperties": true }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Lowered to the model's output limit, and to what is left of its context, when higher." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "top_k": { "type": "integer", "minimum": 0, "description": "Dropped for a provider that does not list it." }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean", "default": false }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Sent to the provider as user." } } }, "provider": { "allOf": [ { "$ref": "#/components/schemas/ProviderPreferences" } ], "description": "Routing preferences as on chat completions; provider.lane (public or attested) and provider.disclosure work as documented there." } }, "additionalProperties": true }, "AnthropicCountTokensRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "A model id from GET /v1/models, or a name the operator mapped with ANTHROPIC_MODEL_MAP." }, "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", "description": "A content block: text, image (source base64 or url), tool_use, tool_result, document (text source only); thinking blocks are dropped.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image", "tool_use", "tool_result", "document", "thinking", "redacted_thinking" ] } }, "additionalProperties": true } } ] } } } }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string" } }, "additionalProperties": true } } ] }, "tools": { "type": "array", "description": "Custom tools (name, description, input_schema). Tools hosted by Anthropic are left out and named in X-Anyroute-Ignored.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": { "type": "object" } }, "additionalProperties": true } }, "tool_choice": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "auto", "any", "tool", "none" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } } }, "thinking": { "type": "object", "description": "Accepted and not acted on.", "additionalProperties": true } }, "additionalProperties": true }, "AnthropicMessage": { "type": "object", "required": [ "id", "type", "role", "model", "content", "stop_reason", "stop_sequence", "usage" ], "properties": { "id": { "type": "string", "description": "The id of the generation's signed receipt (GET /api/v1/receipts/{id})." }, "type": { "const": "message" }, "role": { "const": "assistant" }, "model": { "type": "string", "description": "The catalog model that answered." }, "content": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "tool_use" ] }, "text": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object" } } } }, "stop_reason": { "type": [ "string", "null" ], "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use", "refusal", null ] }, "stop_sequence": { "type": [ "string", "null" ] }, "usage": { "type": "object", "required": [ "input_tokens", "output_tokens" ], "properties": { "input_tokens": { "type": "integer", "description": "Prompt tokens not read from or written to the provider's cache." }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" } } }, "anyroute": { "type": "object", "description": "What the router says about the call.", "properties": { "receipt_id": { "type": "string" }, "lane": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] }, "disclosure": { "type": [ "string", "null" ], "enum": [ "attested", "policy", "vendor-forwarded", null ] }, "policy_hash": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "cost_usd": { "type": [ "number", "null" ] }, "upstream_attestation": { "type": "object", "additionalProperties": true }, "receipt": { "$ref": "#/components/schemas/Receipt" } } } } }, "AnthropicErrorBody": { "type": "object", "required": [ "type", "error" ], "properties": { "type": { "const": "error" }, "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "permission_error", "not_found_error", "request_too_large", "rate_limit_error", "api_error", "timeout_error", "overloaded_error" ] }, "message": { "type": "string" } } }, "request_id": { "type": "string" }, "anyroute": { "type": "object", "description": "The router's own error type (for example lane_unavailable), its metadata, and receipt_id when a refused call was billed.", "additionalProperties": true } } }, "ResponsesInputItem": { "description": "An input item: a message, a function_call or custom_tool_call from an earlier turn, or the function_call_output or custom_tool_call_output for it.", "oneOf": [ { "type": "object", "required": [ "role", "content" ], "properties": { "type": { "const": "message" }, "role": { "type": "string", "enum": [ "user", "assistant", "system", "developer" ], "description": "developer is sent to the model as system." }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "description": "input_text ({type, text}), input_image ({type, image_url: an https or data: URL, detail}); output_text and refusal in an earlier assistant message. File ids and input_file are refused.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "output_text", "refusal" ] } }, "additionalProperties": true } } ] } } }, { "type": "object", "required": [ "type", "call_id", "name" ], "properties": { "type": { "const": "function_call" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON text." } } }, { "type": "object", "required": [ "type", "call_id", "output" ], "properties": { "type": { "const": "function_call_output" }, "call_id": { "type": "string" }, "output": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "description": "The function's result: text, or input_text parts." } } }, { "type": "object", "required": [ "type", "call_id", "name" ], "properties": { "type": { "const": "custom_tool_call" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "string", "description": "The freeform text the model gave the tool." } } }, { "type": "object", "required": [ "type", "call_id", "output" ], "properties": { "type": { "const": "custom_tool_call_output" }, "call_id": { "type": "string" }, "output": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } } } ] }, "ResponsesRequest": { "type": "object", "required": [ "model", "input" ], "description": "A Responses API request. Options AnyRoute cannot honour because they need stored state are refused (store true, previous_response_id, conversation, background, prompt) and so is every tool that is not a function or custom tool.", "properties": { "model": { "type": "string", "description": "Public model ID, as in chat completions." }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResponsesInputItem" } } ], "description": "The whole conversation: one user message as text, or input items. reasoning items are ignored; item_reference and hosted tool items are refused." }, "instructions": { "type": "string", "description": "Sent as a system message before the input." }, "tools": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "function" }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema of the arguments." }, "strict": { "type": "boolean" } } }, { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "custom" }, "name": { "type": "string" }, "description": { "type": "string" }, "format": { "type": "object", "description": "{type: text}, or {type: grammar, syntax: lark or regex, definition}. The grammar is given to the model in the tool's description as guidance and is not enforced.", "properties": { "type": { "type": "string", "enum": [ "text", "grammar" ] }, "syntax": { "type": "string" }, "definition": { "type": "string" } }, "additionalProperties": true } } } ] }, "description": "Function and custom tools. Requires a model and provider that support tools. A custom tool takes freeform text; its name must differ from every function's." }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "auto", "none", "required" ] }, { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "function", "custom" ] }, "name": { "type": "string" } } } ] }, "parallel_tool_calls": { "type": "boolean" }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "text": { "type": "object", "properties": { "format": { "type": "object", "description": "text (default), json_object, or json_schema ({type, name, schema, strict, description}), sent as response_format. Requires a model and provider that support it.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ] } }, "additionalProperties": true } } }, "reasoning": { "type": "object", "properties": { "effort": { "type": "string" } }, "description": "reasoning.effort is passed on as reasoning.effort; providers that do not support it drop it." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Echoed in the Response. Not sent to a provider." }, "user": { "type": "string", "description": "Passed to the provider as the end-user identity, as in chat completions." }, "stream": { "type": "boolean", "default": false }, "store": { "type": "boolean", "enum": [ false ], "default": false, "description": "Must be false or omitted: AnyRoute stores no responses." }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" } }, "additionalProperties": true }, "ResponsesObject": { "type": "object", "required": [ "id", "object", "created_at", "status", "model", "output", "metadata" ], "description": "A Response. The request's instructions, tools, tool_choice, max_output_tokens, temperature, top_p, parallel_tool_calls, text, reasoning and user are echoed back; store is always false and previous_response_id null.", "properties": { "id": { "type": "string", "description": "resp_ followed by the receipt id. There is nothing to fetch with it; the receipt is at GET /api/v1/receipts/{id} for the id without the resp_ prefix." }, "object": { "const": "response" }, "created_at": { "type": "integer" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "failed" ], "description": "incomplete: the answer was cut off (incomplete_details.reason max_output_tokens or content_filter). failed appears only in a stream, in response.failed." }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "incomplete_details": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "enum": [ "max_output_tokens", "content_filter" ] } } }, "model": { "type": "string", "description": "The model the router resolved the request to." }, "output": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "type", "id", "role", "status", "content" ], "properties": { "type": { "const": "message" }, "id": { "type": "string" }, "role": { "const": "assistant" }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "content": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "output_text", "refusal" ] }, "text": { "type": "string" }, "annotations": { "type": "array", "items": {} }, "refusal": { "type": "string" } } } } } }, { "type": "object", "required": [ "type", "id", "call_id", "name", "arguments", "status" ], "properties": { "type": { "const": "function_call" }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON text." }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] } } }, { "type": "object", "required": [ "type", "id", "call_id", "name", "input", "status" ], "properties": { "type": { "const": "custom_tool_call" }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "string", "description": "The freeform text the model gave the custom tool." }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] } } } ] }, "description": "A message with output_text, and a function_call or custom_tool_call item for each tool call the model made." }, "usage": { "type": [ "object", "null" ], "properties": { "input_tokens": { "type": "integer" }, "input_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer" }, "output_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "integer" } } }, "total_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "What the call cost in USD, as usage.cost in chat completions." } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The request's metadata plus anyroute_receipt_id (the id of the signed receipt), anyroute_lane (public, attested or unlinkable), anyroute_disclosure (the class the receipt records, once known) and anyroute_policy_hash (only when the serving endpoint attested one)." } }, "additionalProperties": true }, "RagRequest": { "type": "object", "required": [ "documents", "question", "model" ], "additionalProperties": false, "description": "Unknown fields are refused (400), so a misspelt option is never silently ignored. There is no cache option: the response cache is never used.", "properties": { "documents": { "type": "array", "minItems": 1, "description": "The text to search: plain strings or {id, text}. At most 200 documents and 2 MiB of UTF-8 text by default (RAG_MAX_DOCUMENTS, RAG_MAX_BYTES). A string, or an object without id, is named doc-, starting at 1. Ids must be unique; a document with no text is refused.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "text" ], "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "text": { "type": "string" } } } ] } }, "question": { "type": "string", "minLength": 1, "maxLength": 8000 }, "model": { "type": "string", "description": "The chat model that writes the answer. An embedding model is refused." }, "embedding_model": { "type": "string", "description": "The model that embeds the chunks and the question. Default: qwen/qwen3-embedding-8b if the catalog serves it, else the cheapest embedding model; models with an attested endpoint are considered first unless the request asks for a lane or ceiling, when only models that meet it are." }, "top_k": { "type": "integer", "minimum": 1, "maximum": 20, "default": 4, "description": "How many of the best chunks go into the prompt. A request whose largest possible prompt would not fit the chat model's context is refused (400 context_too_small) before anything is embedded." }, "chunk": { "type": "object", "additionalProperties": false, "description": "Sizes are in characters (UTF-16 code units). A chunk ends at a paragraph, line or sentence boundary when there is one in its last 40%, otherwise at a space.", "properties": { "size": { "type": "integer", "minimum": 100, "maximum": 8000, "default": 1000 }, "overlap": { "type": "integer", "minimum": 0, "description": "Characters shared by neighbouring chunks: at most half of size. Default: 15% of size." } } }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Passed to the chat call." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Passed to the chat call." }, "stream": { "type": "boolean", "default": false }, "include_excerpts": { "type": "boolean", "default": false, "description": "Return each source's text as excerpt. Off by default: the response then carries where each source lies (start, end) and never the text." }, "provider": { "type": "object", "additionalProperties": false, "description": "The lane and disclosure ceiling, applied to every call. Other routing options are not accepted. If you send none, the lane pinned on the key (routing.provider) is used, and if there is none the router chooses (see the operation description).", "properties": { "lane": { "type": "string", "enum": [ "public", "attested" ], "description": "attested: every call goes only to a provider with attested retention and a fresh attestation the router verified; when one cannot be served the request is refused, never downgraded. unlinkable is not available here (400)." }, "disclosure": { "type": "string", "enum": [ "none", "policy", "any" ], "description": "Same as provider.disclosure on chat completions." } } } } }, "RagSource": { "type": "object", "required": [ "ref", "document_id", "chunk_index", "score", "start", "end" ], "properties": { "ref": { "type": "integer", "description": "The number of the source in the prompt, and in the citations ([1], [2]) the model was asked to make. Sources are in rank order." }, "document_id": { "type": "string" }, "chunk_index": { "type": "integer", "description": "Position of the chunk within its document, from 0." }, "score": { "type": "number", "description": "Cosine similarity of the chunk's vector with the question's, rounded to 6 places." }, "start": { "type": "integer" }, "end": { "type": "integer", "description": "The chunk is the document text from start to end (characters)." }, "excerpt": { "type": "string", "description": "The chunk's text. Present only when include_excerpts is true." } } }, "RagCall": { "type": "object", "required": [ "step", "receipt_id", "lane", "disclosure", "cost", "tokens" ], "description": "One provider call, as its signed receipt records it. Read the receipt with GET /api/v1/receipts/{receipt_id}.", "properties": { "step": { "type": "string", "enum": [ "embeddings", "chat" ] }, "receipt_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "lane": { "type": [ "string", "null" ], "description": "The lane the call was made under." }, "disclosure": { "type": [ "string", "null" ], "enum": [ "attested", "policy", "vendor-forwarded", null ], "description": "The class the call was served under, from its receipt." }, "cost": { "type": "number", "description": "USD charged for this call." }, "tokens": { "type": "object", "properties": { "prompt": { "type": "integer" }, "completion": { "type": "integer" } } }, "inputs": { "type": "integer", "description": "Embeddings calls: how many texts (the question and chunks) the call embedded." }, "policy_hash": { "type": [ "string", "null" ], "description": "The classifier policy hash the serving endpoint attested, when it did (X-Anyroute-Policy-Hash of that call)." }, "upstream_attestation": { "type": "object", "description": "For an attested gateway: what the router checked of the gateway's receipt for this call. attested is true only when the receipt shows an upstream the gateway verified inside a TEE.", "properties": { "attested": { "type": "boolean" }, "gpu_attested": { "type": "boolean" }, "receipt_verified": { "type": "boolean" }, "kind": {}, "receipt_id": {}, "reason": { "type": "string" } } }, "withheld": { "const": true, "description": "The provider had answered, but the router withheld the reply because the receipt did not show an attested upstream. The call is billed; its signed receipt says why." }, "attestation_simulated": { "const": true, "description": "The attestation behind this call is a development report; a production router refuses those." } } }, "RagAnswer": { "type": "object", "required": [ "id", "object", "answer", "sources", "receipts", "lane", "lane_source", "embedding_model", "retrieval", "usage" ], "properties": { "id": { "type": "string", "description": "The chat call's receipt id: the same as X-Receipt-Id." }, "object": { "const": "rag.answer" }, "model": { "type": "string", "description": "The chat model that answered." }, "answer": { "type": "string" }, "finish_reason": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/RagSource" } }, "receipts": { "type": "array", "description": "Every provider call the request made, in order: the embeddings calls, then the chat call.", "items": { "$ref": "#/components/schemas/RagCall" } }, "embedding_model": { "type": "string" }, "lane": { "type": "string", "enum": [ "public", "attested" ], "description": "The lane every call was made under." }, "lane_source": { "type": "string", "enum": [ "request", "default" ], "description": "request: you stated a lane or a disclosure ceiling (even public or any) and it was used as stated. default: you stated none, and the router chose attested when the chat model and the embedding model both have an attested endpoint, else public." }, "lane_note": { "type": "string", "description": "Present when the default lane was public: which model had no known attested endpoint." }, "disclosure": { "type": [ "string", "null" ], "enum": [ "attested", "policy", "vendor-forwarded", null ], "description": "The weakest class among all the calls, from their receipts; null when a call's class is not known." }, "attestation_simulated": { "const": true, "description": "Present when any call's attestation was a development report." }, "retrieval": { "type": "object", "properties": { "documents": { "type": "integer" }, "chunks": { "type": "integer" }, "top_k": { "type": "integer" }, "chunk": { "type": "object", "properties": { "size": { "type": "integer" }, "overlap": { "type": "integer" } } }, "embedding_calls": { "type": "integer" } } }, "usage": { "type": "object", "properties": { "embedding_tokens": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "Total USD across all calls." }, "cost_usd": { "type": "string", "description": "The same total, exact." } } } } }, "TlogCheckpoint": { "type": "object", "required": [ "size", "root_hash", "note", "cosigned_by", "witnessed" ], "properties": { "size": { "type": "integer", "minimum": 0 }, "root_hash": { "type": "string", "description": "Base64 (standard, padded) 32-byte hash.", "contentEncoding": "base64" }, "note": { "type": "string", "description": "The signed note, as served at /tlog/checkpoint." }, "cosigned_by": { "type": "array", "items": { "type": "string" }, "description": "Names of the configured witnesses whose cosignatures are attached." }, "witnessed": { "type": "boolean", "description": "True when at least the quorum of configured witnesses cosigned." }, "rekor": { "oneOf": [ { "$ref": "#/components/schemas/TlogRekorAnchor" }, { "type": "null" } ], "description": "Present only with Rekor anchoring on: this checkpoint's Rekor entry, or null until it is anchored." } } }, "TlogInfo": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "origin", "verifier_key", "kinds", "witnesses", "quorum", "size", "checkpoint" ], "properties": { "origin": { "type": "string", "description": "Checkpoint origin and the log's key name." }, "verifier_key": { "type": "string", "description": "Signed-note verifier key ++." }, "formats": { "type": "object", "additionalProperties": { "type": "string" } }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "receipt_key", "ohttp_key_config", "blind_issuer_key", "measurement_bundle", "attestation_binding", "data_inventory", "host_policy" ] } }, "witnesses": { "type": "array", "items": { "type": "object", "required": [ "name", "verifier_key" ], "properties": { "name": { "type": "string" }, "verifier_key": { "type": "string", "description": "++, a cosignature/v1 key." } } } }, "quorum": { "type": "integer", "minimum": 1 }, "size": { "type": "integer", "minimum": 0 }, "checkpoint": { "$ref": "#/components/schemas/TlogCheckpoint" }, "witnessed_size": { "type": [ "integer", "null" ], "description": "Tree size of the newest checkpoint the quorum cosigned." }, "tiles_url": { "type": "string", "format": "uri" }, "rekor": { "type": [ "object", "null" ], "description": "Rekor anchoring (TLOG_REKOR_ENABLED): the same fields as GET /api/v1/tlog/rekor without the list; null when anchoring is off.", "properties": { "rekor_url": { "type": "string", "format": "uri" }, "entry_type": { "type": "string" }, "algorithm": { "type": "string", "enum": [ "ecdsa-p256-sha256" ] }, "key_id": { "type": "string", "description": "SHA-256 of the key's SubjectPublicKeyInfo, hex.", "pattern": "^[0-9a-f]{64}$" }, "public_key_pem": { "type": "string", "description": "The anchoring key, an ECDSA P-256 public key (PEM)." }, "min_interval_ms": { "type": "integer" }, "latest": { "oneOf": [ { "$ref": "#/components/schemas/TlogRekorAnchor" }, { "type": "null" } ] } } } } } } }, "TlogEntry": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "index", "kind", "sha256", "subject", "entry", "leaf_hash" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "kind": { "type": "string", "enum": [ "receipt_key", "ohttp_key_config", "blind_issuer_key", "measurement_bundle", "attestation_binding", "data_inventory", "host_policy" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "subject": { "type": "string", "description": "The key id, epoch or provider the entry is about." }, "entry": { "type": "string", "description": "The entry's canonical JSON; its leaf hash is SHA-256(0x00 || these bytes)." }, "leaf_hash": { "type": "string", "description": "Base64 (standard, padded) 32-byte hash.", "contentEncoding": "base64" } } } } }, "TlogConsistency": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "from", "to", "proof" ], "properties": { "from": { "type": "integer", "minimum": 0 }, "to": { "type": "integer", "minimum": 0 }, "proof": { "type": "array", "items": { "type": "string", "description": "Base64 (standard, padded) 32-byte hash.", "contentEncoding": "base64" } } } } } }, "TlogProof": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "origin", "index", "kind", "sha256", "entry", "checkpoint", "inclusion" ], "properties": { "origin": { "type": "string" }, "index": { "type": "integer", "minimum": 0 }, "kind": { "type": "string", "enum": [ "receipt_key", "ohttp_key_config", "blind_issuer_key", "measurement_bundle", "attestation_binding", "data_inventory", "host_policy" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "subject": { "type": "string", "description": "The key id, epoch or provider the entry is about." }, "entry": { "type": "string", "description": "The entry's canonical JSON; its leaf hash is SHA-256(0x00 || these bytes)." }, "checkpoint": { "$ref": "#/components/schemas/TlogCheckpoint" }, "inclusion": { "type": "array", "items": { "type": "string", "description": "Base64 (standard, padded) 32-byte hash.", "contentEncoding": "base64" }, "description": "RFC 6962 inclusion proof from the entry's leaf to checkpoint.root_hash." }, "consistency": { "type": [ "object", "null" ], "required": [ "from", "to", "proof" ], "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "proof": { "type": "array", "items": { "type": "string", "description": "Base64 (standard, padded) 32-byte hash.", "contentEncoding": "base64" } } } } } } } }, "TlogCosignatureResult": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "size", "accepted", "cosignatures", "witnessed" ], "properties": { "size": { "type": "integer" }, "accepted": { "type": "array", "items": { "type": "string" }, "description": "Witnesses whose cosignature on this note verified." }, "cosignatures": { "type": "integer", "description": "Configured witnesses that have now cosigned this tree size." }, "witnessed": { "type": "boolean" } } } } }, "TlogRekorKey": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "algorithm", "key_id", "public_key_pem" ], "properties": { "algorithm": { "type": "string", "enum": [ "ecdsa-p256-sha256" ] }, "key_id": { "type": "string", "description": "SHA-256 of the key's SubjectPublicKeyInfo, hex.", "pattern": "^[0-9a-f]{64}$" }, "public_key_pem": { "type": "string", "description": "The anchoring key, an ECDSA P-256 public key (PEM)." } } } } }, "TlogRekorAnchor": { "type": "object", "description": "A Rekor entry that anchors one checkpoint. Rekor's own hashes (inclusion_proof) are hex, as Rekor writes them.", "required": [ "size", "root_hash", "note", "artifact_sha256", "key_id", "rekor_url", "uuid", "log_index", "integrated_time", "entry_url", "body", "inclusion_proof", "verified", "anchored_at" ], "properties": { "size": { "type": "integer", "minimum": 1 }, "root_hash": { "type": "string", "contentEncoding": "base64", "description": "The checkpoint's root hash, base64 as in checkpoints." }, "note": { "type": "string", "description": "The artifact: the checkpoint text, a blank line and the log's own signature line." }, "artifact_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of note; the hash the hashedrekord entry holds (search.sigstore.dev finds the entry by it)." }, "key_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The anchoring key that signed the entry." }, "rekor_url": { "type": "string", "format": "uri" }, "uuid": { "type": "string", "description": "The entry's uuid (tree id and leaf hash, hex)." }, "log_index": { "type": [ "integer", "null" ] }, "integrated_time": { "type": [ "integer", "null" ], "description": "When Rekor integrated the entry (seconds since the Unix epoch)." }, "log_id": { "type": [ "string", "null" ] }, "entry_url": { "type": "string", "format": "uri" }, "search_url": { "type": [ "string", "null" ], "format": "uri", "description": "The entry on search.sigstore.dev, for the public Rekor instance." }, "body": { "type": [ "string", "null" ], "contentEncoding": "base64", "description": "The entry body as Rekor returned it; its leaf hash is SHA-256(0x00 || body)." }, "inclusion_proof": { "type": [ "object", "null" ], "required": [ "log_index", "tree_size", "root_hash", "hashes" ], "properties": { "log_index": { "type": "integer" }, "tree_size": { "type": "integer" }, "root_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "hashes": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "checkpoint": { "type": [ "string", "null" ], "description": "Rekor's signed checkpoint for tree_size and root_hash." } } }, "signed_entry_timestamp": { "type": [ "string", "null" ], "contentEncoding": "base64" }, "verified": { "type": "object", "required": [ "inclusion", "checkpoint_signature", "signed_entry_timestamp" ], "description": "What the router checked when it stored the entry; checkpoint_signature and signed_entry_timestamp need REKOR_PUBLIC_KEY.", "properties": { "inclusion": { "type": "boolean" }, "checkpoint_signature": { "type": "boolean" }, "signed_entry_timestamp": { "type": "boolean" } } }, "anchored_at": { "type": "string", "format": "date-time" } } }, "TlogRekorAnchors": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "rekor_url", "entry_type", "algorithm", "key_id", "public_key_pem", "min_interval_ms", "latest", "anchors", "next_before" ], "properties": { "rekor_url": { "type": "string", "format": "uri" }, "entry_type": { "type": "string", "enum": [ "hashedrekord" ] }, "algorithm": { "type": "string", "enum": [ "ecdsa-p256-sha256" ] }, "key_id": { "type": "string", "description": "SHA-256 of the key's SubjectPublicKeyInfo, hex.", "pattern": "^[0-9a-f]{64}$" }, "public_key_pem": { "type": "string", "description": "The anchoring key, an ECDSA P-256 public key (PEM)." }, "min_interval_ms": { "type": "integer", "description": "At most one submission to Rekor per this many milliseconds." }, "latest": { "oneOf": [ { "$ref": "#/components/schemas/TlogRekorAnchor" }, { "type": "null" } ], "description": "The newest anchored checkpoint under the current key." }, "anchors": { "type": "array", "items": { "$ref": "#/components/schemas/TlogRekorAnchor" } }, "next_before": { "type": [ "integer", "null" ], "description": "Pass as before for the next page; null on the last page." } } } } }, "PrivacyLabel": { "type": "object", "required": [ "receipt_id", "lane", "label", "summary", "short", "verify_url" ], "description": "The privacy label for one answer, computed from its signed receipt (privacyLabel in @anyroute/client computes the same object from a receipt you hold; teeKind and the unlinkable transports are the two things it takes from the router).", "properties": { "receipt_id": { "type": [ "string", "null" ] }, "lane": { "type": [ "string", "null" ], "enum": [ "public", "attested", "unlinkable", null ], "description": "The lane the receipt records, or null for a receipt that predates lanes." }, "label": { "type": "object", "required": [ "prompt_readers", "network", "payment", "stored", "hardware" ], "properties": { "output": { "type": "object", "required": [ "unit_type", "units", "kind", "text" ], "properties": { "unit_type": { "type": "string" }, "units": { "type": [ "number", "null" ] }, "kind": { "type": "string", "enum": [ "text", "image", "video", "audio", "call", "compute", "unknown" ] }, "text": { "type": "string" } }, "description": "Usage unit and quantity from the receipt. Missing unit types default to token; unfamiliar types carry no inferred content-retention guarantee." }, "prompt_readers": { "type": "object", "required": [ "router", "provider", "text" ], "properties": { "participants": { "type": "array", "items": { "type": "string" }, "description": "Provider ids named in an aggregate council receipt; individual receipts describe their access." }, "router": { "type": "boolean", "const": true, "description": "Always true: the router reads the prompt in memory to route it, on every lane." }, "provider": { "type": "object", "required": [ "id", "access", "reply_withheld" ], "properties": { "id": { "type": [ "string", "null" ] }, "access": { "type": "string", "enum": [ "attested_enclave", "documented_policy", "provider", "unproven_provider", "unknown", "none" ], "description": "attested_enclave: the router had verified the provider's hardware attestation (and, for a gateway, its signed receipt checked out). documented_policy: a no-retention policy the provider states, not proven by hardware. provider: may keep or log the prompt under its own terms. unproven_provider: an attested enclave was required or reported and not shown. unknown: the receipt does not say. none: served from the response cache, no provider ran." }, "reply_withheld": { "type": [ "boolean", "null" ], "description": "true when the router withheld the reply because the attested-enclave check failed; null when the receipt does not show which." } } }, "text": { "type": "string" } } }, "network": { "type": "object", "required": [ "hidden", "via", "stored", "counter", "text" ], "properties": { "hidden": { "type": "boolean", "description": "true only on the unlinkable lane." }, "via": { "type": [ "string", "null" ], "enum": [ "tor", "relay", "tor_or_relay", null ] }, "stored": { "type": [ "boolean", "null" ], "enum": [ false, null ], "description": "AnyRoute's software writes the client address to no table on current routes; null means handling is not established for an unfamiliar output type." }, "counter": { "type": "string", "enum": [ "none", "about_a_minute", "possible" ], "description": "Whether the address was the key of a rate-limit counter that expires about a minute later. Calls with an API key are limited per key (none); a call with no key is limited per address (about_a_minute); possible when the receipt does not say which." }, "text": { "type": "string" } } }, "payment": { "type": "object", "required": [ "kind", "identifies", "text" ], "properties": { "kind": { "type": "string", "enum": [ "key_balance", "pay_with_stock_token", "own_provider_key", "blind_token", "wallet_balance", "x402", "cache_hit", "unknown" ] }, "identifies": { "type": [ "string", "null" ], "enum": [ "api_key", "wallet", "spent_token", null ], "description": "What the receipt names as the payer: a key hash, a wallet address, or only the hash of a spent blind token." }, "text": { "type": "string" } } }, "stored": { "type": "object", "required": [ "prompt_text", "reply_text", "client_address", "fingerprints", "linked_to", "cache", "records", "public_by_id", "text" ], "properties": { "prompt_text": { "type": [ "boolean", "null" ], "enum": [ false, null ] }, "reply_text": { "type": [ "boolean", "null" ], "enum": [ false, null ] }, "client_address": { "type": [ "boolean", "null" ], "enum": [ false, null ] }, "fingerprints": { "type": "boolean", "description": "SHA-256 fingerprints of the request and the reply are kept." }, "linked_to": { "type": "string", "enum": [ "api_key", "wallet", "nobody", "unknown" ] }, "cache": { "type": "string", "enum": [ "never", "only_if_requested", "cache_hit", "not_recorded" ], "description": "The opt-in response cache holds an encrypted copy of the reply, never the prompt itself, until it expires; semantic caching also keeps a hashed word vector. Unrecognized content paths report eligibility as not_recorded. It is never used on the attested or unlinkable lanes or with a blind token; on the public lane only if the request asked for it." }, "records": { "type": "array", "items": { "type": "string" } }, "public_by_id": { "type": "boolean", "const": true }, "text": { "type": "string" } } }, "hardware": { "type": "object", "required": [ "attested", "tee", "gpu_attested", "verified_by", "development_report", "text" ], "properties": { "attested": { "type": "boolean" }, "tee": { "type": [ "string", "null" ], "description": "The TEE type from the router's attestation record for the receipt's attestation hash, when the receipt cites one; null when not known." }, "gpu_attested": { "type": "boolean", "description": "true only when the gateway's signed receipt asserted GPU attestation." }, "verified_by": { "type": [ "string", "null" ], "enum": [ "gateway_receipt", "router_attestation", null ] }, "development_report": { "type": "boolean", "description": "true when the attestation behind the call was a development report, which is not a hardware proof." }, "text": { "type": "string" } } } } }, "summary": { "type": "array", "minItems": 3, "maxItems": 5, "items": { "type": "string" }, "description": "Three to five short lines a person who is not a developer can read." }, "short": { "type": "string", "description": "The same in one line, for a chat message." }, "verify_url": { "type": [ "string", "null" ], "description": "The verify page for this receipt, when the router's address is known." } } }, "BatchRequestLine": { "type": "object", "required": [ "custom_id", "method", "url", "body" ], "properties": { "custom_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Your id for the line, unique in the batch; results carry it back." }, "method": { "type": "string", "enum": [ "POST" ] }, "url": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/embeddings", "/api/v1/chat/completions", "/api/v1/embeddings" ] }, "body": { "type": "object", "additionalProperties": true, "description": "The chat completions or embeddings request body. stream true, model anyroute/council and verify are refused." } } }, "BatchCreateRequest": { "type": "object", "description": "Send requests or input_jsonl. input_file_id is refused with 400 (there is no files endpoint).", "oneOf": [ { "required": [ "requests" ] }, { "required": [ "input_jsonl" ] } ], "properties": { "requests": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BatchRequestLine" } }, "input_jsonl": { "type": "string", "description": "The lines as JSON Lines text: one BatchRequestLine object per line." }, "endpoint": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/embeddings" ], "description": "When given, every line's url must match it." }, "completion_window": { "type": "string", "enum": [ "24h" ], "default": "24h" } } }, "Batch": { "type": "object", "required": [ "id", "object", "status", "completion_window", "created_at", "request_counts", "cost", "output_url", "errors_url" ], "properties": { "id": { "type": "string", "description": "batch_ followed by a random id." }, "object": { "type": "string", "const": "batch" }, "endpoint": { "type": [ "string", "null" ], "description": "The endpoint of the lines, as sent or as the lines' url." }, "errors": { "type": [ "object", "null" ], "description": "Problems found in the batch as a whole, else null.", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "line": { "type": [ "integer", "null" ] } } } } } }, "input_file_id": { "type": "null", "description": "Always null: the lines are sent inline." }, "completion_window": { "type": "string", "const": "24h" }, "status": { "type": "string", "enum": [ "validating", "in_progress", "completed", "failed", "expired", "cancelling", "cancelled" ], "description": "validating: accepted, waiting for the worker. completed, failed, expired and cancelled are final." }, "output_file_id": { "type": "null", "description": "Always null: read the results at output_url." }, "error_file_id": { "type": "null", "description": "Always null: read the errors at errors_url." }, "output_url": { "type": "string", "description": "/api/v1/batches/{id}/output" }, "errors_url": { "type": "string", "description": "/api/v1/batches/{id}/errors" }, "created_at": { "type": "integer", "description": "Unix seconds." }, "in_progress_at": { "type": [ "integer", "null" ], "description": "Unix seconds, or null." }, "expires_at": { "type": [ "integer", "null" ], "description": "When unfinished lines expire (the end of the completion window), unix seconds." }, "finalizing_at": { "type": [ "integer", "null" ], "description": "Unix seconds, or null." }, "completed_at": { "type": [ "integer", "null" ], "description": "Unix seconds, or null." }, "failed_at": { "type": [ "integer", "null" ], "description": "Unix seconds, or null." }, "expired_at": { "type": [ "integer", "null" ], "description": "Unix seconds, or null." }, "cancelling_at": { "type": [ "integer", "null" ], "description": "Unix seconds, or null." }, "cancelled_at": { "type": [ "integer", "null" ], "description": "Unix seconds, or null." }, "request_counts": { "type": "object", "required": [ "total", "completed", "failed" ], "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" } } }, "cost": { "type": "object", "required": [ "usd", "discount_bps", "list_usd" ], "properties": { "usd": { "type": "number", "description": "What the answered lines cost so far, at the batch price." }, "discount_bps": { "type": "integer", "description": "The discount in basis points; 5000 is half the normal price." }, "list_usd": { "type": "number", "description": "What the same lines would cost as normal calls." } } }, "results_expire_at": { "type": [ "integer", "null" ], "description": "When the output and errors files are deleted, unix seconds; null until the batch finishes." }, "metadata": { "type": "null" } } }, "BatchList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Batch" } }, "first_id": { "type": [ "string", "null" ] }, "last_id": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "BatchResultLine": { "type": "object", "required": [ "id", "custom_id", "response", "error" ], "properties": { "id": { "type": "string", "description": "batch_req_ followed by a random id." }, "custom_id": { "type": "string" }, "response": { "type": [ "object", "null" ], "description": "The response to the line; null for a line that never ran.", "properties": { "status_code": { "type": "integer" }, "request_id": { "type": [ "string", "null" ], "description": "The generation id (and receipt id) of an answered line." }, "body": { "type": "object", "additionalProperties": true, "description": "The normal response body (usage.cost and receipt included), or { error } for a failed line." } } }, "error": { "type": [ "object", "null" ], "description": "null for an answered line.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "PresetDocument": { "type": "object", "additionalProperties": false, "required": [ "models" ], "description": "A preset: the routing part of a saved route plus prompt-side defaults. The whole document is at most 64 KB as JSON.", "properties": { "anyroute": { "$ref": "#/components/schemas/StructuredOutputOptions" }, "description": { "type": "string", "maxLength": 280 }, "models": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "string" }, "description": "Catalog model ids in fallback order; no @route/ or @preset/ entries." }, "provider": { "type": "object", "description": "The same provider preferences as a saved route (SavedRouteConfig.provider), including lane (public|attested) and disclosure (none|policy|any), where the stricter of the preset and the request applies." }, "params": { "type": "object", "description": "The same closed list of sampling defaults as a saved route (SavedRouteConfig.params). Request values win." }, "system_prompt": { "type": "string", "minLength": 1, "maxLength": 16000, "description": "Prepended as a system message only when the request's messages have no system or developer message. Chat completions only." }, "response_format": { "type": "object", "description": "text, json_object or json_schema (at most 16 KB). Used when the request sets no response_format." }, "tools": { "type": "array", "maxItems": 32, "items": { "type": "object" }, "description": "Function tool definitions (unique names, at most 32 KB). Used with tool_choice when the request sets no tools." }, "tool_choice": { "description": "none, auto, required, or a function the preset's tools define.", "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object" } ] } } }, "Preset": { "type": "object", "required": [ "name", "model", "version", "hash", "config" ], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" }, "model": { "type": "string", "description": "Use as the request model, e.g. @preset/support; add @ to pin one." }, "description": { "type": "string" }, "version": { "type": "integer", "minimum": 1, "description": "The version shown: the latest unless one was asked for." }, "hash": { "type": "string", "description": "SHA-256 (hex) of the version's canonical JSON. Equal content, equal hash." }, "config": { "$ref": "#/components/schemas/PresetDocument" }, "versions": { "type": "integer", "description": "In the list: how many versions the preset has." }, "latest_version": { "type": "integer" }, "changed": { "type": "boolean", "description": "PUT and rollback: false when the document equals the latest version, so no version was added." }, "restored_from": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PresetVersion": { "type": "object", "required": [ "version", "hash", "model", "source", "created_at" ], "properties": { "version": { "type": "integer", "minimum": 1 }, "hash": { "type": "string" }, "model": { "type": "string", "description": "The pinned model name, e.g. @preset/support@3." }, "source": { "type": "string", "enum": [ "put", "rollback" ] }, "restored_from": { "type": "integer", "description": "For a rollback: the version whose content it copied." }, "created_at": { "type": "string", "format": "date-time" } } }, "PresetDiff": { "type": "object", "required": [ "name", "from", "to", "identical", "changes" ], "properties": { "name": { "type": "string" }, "from": { "$ref": "#/components/schemas/PresetVersion" }, "to": { "$ref": "#/components/schemas/PresetVersion" }, "identical": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "required": [ "op", "path" ], "properties": { "op": { "type": "string", "enum": [ "add", "remove", "replace" ] }, "path": { "type": "string", "description": "JSON Pointer into the preset document." }, "from": {}, "to": {} } } } } }, "OllamaModel": { "type": "object", "required": [ "name", "model", "modified_at", "size", "digest", "details" ], "properties": { "name": { "type": "string", "examples": [ "meta-llama/llama-3.3-70b-instruct:latest" ] }, "model": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "size": { "type": "integer", "const": 0 }, "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "details": { "type": "object", "properties": { "parent_model": { "type": "string" }, "format": { "type": "string" }, "family": { "type": "string" }, "families": { "type": "array", "items": { "type": "string" } }, "parameter_size": { "type": "string" }, "quantization_level": { "type": "string" } } } } }, "OllamaShowResponse": { "type": "object", "required": [ "details", "capabilities", "model_info" ], "properties": { "modelfile": { "type": "string" }, "parameters": { "type": "string" }, "template": { "type": "string" }, "details": { "type": "object", "properties": { "parent_model": { "type": "string" }, "format": { "type": "string" }, "family": { "type": "string" }, "families": { "type": "array", "items": { "type": "string" } }, "parameter_size": { "type": "string" }, "quantization_level": { "type": "string" } } }, "model_info": { "type": "object", "description": "general.architecture, general.parameter_count where the name states it, and .context_length." }, "capabilities": { "type": "array", "items": { "enum": [ "completion", "tools", "vision", "thinking", "embedding" ] } }, "modified_at": { "type": "string", "format": "date-time" }, "anyroute": { "type": "object", "properties": { "id": { "type": "string" }, "lanes": { "type": "array", "items": { "type": "string" } }, "context_length": { "type": "integer" } } } } }, "OllamaChatRequest": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "A name from GET /ollama/api/tags. :latest names the model itself." }, "stream": { "type": "boolean", "default": true }, "format": { "description": "\"json\" for JSON mode, or a JSON schema for structured output (response_format).", "oneOf": [ { "const": "json" }, { "type": "object" } ] }, "options": { "type": "object", "description": "temperature, top_p, top_k, min_p, seed, stop, frequency_penalty and presence_penalty map directly; repeat_penalty to repetition_penalty; num_predict to max_tokens (-1 and -2 set no limit). Other options tune a local runtime and are named in X-Anyroute-Ignored.", "properties": { "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "number" }, "min_p": { "type": "number" }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "repeat_penalty": { "type": "number" }, "seed": { "type": "integer" }, "num_predict": { "type": "integer" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "think": { "description": "false leaves the model's reasoning out of the reply.", "oneOf": [ { "type": "boolean" }, { "enum": [ "low", "medium", "high" ] } ] }, "keep_alive": { "description": "Accepted and ignored; 0 with no messages or prompt answers done_reason unload." }, "provider": { "type": "object", "description": "The router's provider preferences, as on chat completions, for example {\"lane\":\"attested\"}." }, "messages": { "type": "array", "items": { "type": "object", "required": [ "role" ], "properties": { "role": { "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" }, "description": "Base64 images (user messages); the media type is read from the bytes." }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "id": { "type": "string" }, "function": { "type": "object", "required": [ "name", "arguments" ], "properties": { "index": { "type": "integer" }, "name": { "type": "string" }, "arguments": { "type": "object" } } } } } }, "tool_name": { "type": "string", "description": "On a tool message: the tool whose call it answers." }, "tool_call_id": { "type": "string" }, "thinking": { "type": "string" } } } }, "tools": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "type": { "const": "function" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object" } } } } } } } }, "OllamaGenerateRequest": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "A name from GET /ollama/api/tags. :latest names the model itself." }, "stream": { "type": "boolean", "default": true }, "format": { "description": "\"json\" for JSON mode, or a JSON schema for structured output (response_format).", "oneOf": [ { "const": "json" }, { "type": "object" } ] }, "options": { "type": "object", "description": "temperature, top_p, top_k, min_p, seed, stop, frequency_penalty and presence_penalty map directly; repeat_penalty to repetition_penalty; num_predict to max_tokens (-1 and -2 set no limit). Other options tune a local runtime and are named in X-Anyroute-Ignored.", "properties": { "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "number" }, "min_p": { "type": "number" }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "repeat_penalty": { "type": "number" }, "seed": { "type": "integer" }, "num_predict": { "type": "integer" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "think": { "description": "false leaves the model's reasoning out of the reply.", "oneOf": [ { "type": "boolean" }, { "enum": [ "low", "medium", "high" ] } ] }, "keep_alive": { "description": "Accepted and ignored; 0 with no messages or prompt answers done_reason unload." }, "provider": { "type": "object", "description": "The router's provider preferences, as on chat completions, for example {\"lane\":\"attested\"}." }, "prompt": { "type": "string" }, "system": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "suffix": { "type": "string", "description": "Accepted and named in X-Anyroute-Ignored." }, "template": { "type": "string", "description": "Accepted and named in X-Anyroute-Ignored." }, "raw": { "type": "boolean" }, "context": { "type": "array", "items": { "type": "integer" }, "description": "Deprecated in Ollama; accepted and named in X-Anyroute-Ignored." } } }, "OllamaChatResponse": { "type": "object", "required": [ "model", "created_at", "done" ], "properties": { "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "message": { "type": "object", "properties": { "role": { "const": "assistant" }, "content": { "type": "string" }, "thinking": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "id": { "type": "string" }, "function": { "type": "object", "required": [ "name", "arguments" ], "properties": { "index": { "type": "integer" }, "name": { "type": "string" }, "arguments": { "type": "object" } } } } } } } }, "done": { "type": "boolean" }, "done_reason": { "enum": [ "stop", "length", "load", "unload" ] }, "total_duration": { "type": "integer", "description": "Nanoseconds." }, "load_duration": { "type": "integer", "const": 0 }, "prompt_eval_count": { "type": "integer" }, "prompt_eval_duration": { "type": "integer" }, "eval_count": { "type": "integer" }, "eval_duration": { "type": "integer" }, "anyroute": { "type": "object", "description": "On the closing object: the receipt and where the call was served.", "properties": { "receipt_id": { "type": [ "string", "null" ] }, "lane": { "type": [ "string", "null" ] }, "disclosure": { "type": [ "string", "null" ] }, "policy_hash": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "cost_usd": { "type": [ "number", "null" ] } } } } }, "OllamaGenerateResponse": { "type": "object", "required": [ "model", "created_at", "done" ], "properties": { "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "response": { "type": "string" }, "thinking": { "type": "string" }, "done": { "type": "boolean" }, "done_reason": { "enum": [ "stop", "length", "load", "unload" ] }, "total_duration": { "type": "integer", "description": "Nanoseconds." }, "load_duration": { "type": "integer", "const": 0 }, "prompt_eval_count": { "type": "integer" }, "prompt_eval_duration": { "type": "integer" }, "eval_count": { "type": "integer" }, "eval_duration": { "type": "integer" }, "anyroute": { "type": "object", "description": "On the closing object: the receipt and where the call was served.", "properties": { "receipt_id": { "type": [ "string", "null" ] }, "lane": { "type": [ "string", "null" ] }, "disclosure": { "type": [ "string", "null" ] }, "policy_hash": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "cost_usd": { "type": [ "number", "null" ] } } } } }, "OllamaErrorBody": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } }, "additionalProperties": false }, "TracingSettings": { "type": "object", "description": "Where to send one span per public-lane call made with this key. Calls on the attested and unlinkable lanes are never exported. URLs must be public https:// addresses. The endpoint, headers and keys are encrypted at rest and never returned. A secret left out of a PATCH keeps the stored one when the type is unchanged.", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "otlp", "langfuse", "helicone" ], "description": "otlp: OTLP/HTTP JSON to your collector. langfuse: Langfuse public ingestion API. helicone: Helicone custom log API." }, "endpoint": { "type": "string", "format": "uri", "maxLength": 2048, "description": "otlp: collector base URL; /v1/traces is appended unless present. No query string." }, "headers": { "type": "object", "maxProperties": 16, "additionalProperties": { "type": "string", "maxLength": 4096 }, "description": "otlp: headers sent with every export, e.g. x-honeycomb-team or Authorization. Write-only." }, "host": { "type": "string", "format": "uri", "description": "langfuse (default https://cloud.langfuse.com) or helicone (default https://api.worker.helicone.ai)." }, "public_key": { "type": "string", "description": "langfuse public key." }, "secret_key": { "type": "string", "writeOnly": true, "description": "langfuse secret key. Write-only." }, "api_key": { "type": "string", "writeOnly": true, "description": "helicone API key. Write-only." }, "include_content": { "type": "boolean", "default": false, "description": "Also export the prompt messages and the completion text. Off unless set." }, "enabled": { "type": "boolean", "default": true } } }, "Tracing": { "type": "object", "description": "A key's tracing destination as the API returns it: no URL path, header value or secret.", "required": [ "type", "enabled", "include_content", "target", "header_names", "secrets_set", "updated_at" ], "properties": { "type": { "type": "string", "enum": [ "otlp", "langfuse", "helicone" ] }, "enabled": { "type": "boolean" }, "include_content": { "type": "boolean" }, "target": { "type": "string", "description": "Scheme and host only, e.g. https://api.honeycomb.io/…" }, "header_names": { "type": "array", "items": { "type": "string" } }, "public_key_hint": { "type": [ "string", "null" ], "description": "langfuse: the public key's first and last characters." }, "secrets_set": { "type": "boolean", "const": true }, "updated_at": { "type": "string", "format": "date-time" }, "status": { "type": [ "object", "null" ], "description": "This router process's export counters for the key (GET /api/v1/keys/{hash} and PATCH only). null before the first export.", "properties": { "queued": { "type": "integer" }, "exported": { "type": "integer" }, "dropped": { "type": "integer", "description": "Dropped because the queue was full or the circuit was open." }, "failed": { "type": "integer", "description": "Given up after retries." }, "retries": { "type": "integer" }, "circuit": { "type": "string", "enum": [ "closed", "open", "half_open" ] }, "last_error": { "type": [ "string", "null" ], "description": "http_, timeout, network or destination_blocked." }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "RerankRequest": { "type": "object", "required": [ "model", "query", "documents" ], "properties": { "model": { "type": "string", "description": "A catalogue model whose architecture.output_modalities include rerank (GET /api/v1/models?output_modalities=rerank), optionally with :nitro (fastest providers first) or :floor (cheapest first)." }, "query": { "type": "string", "minLength": 1 }, "documents": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } } ] }, "description": "Strings, or objects with a text. Sent to the provider as strings." }, "top_n": { "type": "integer", "minimum": 1, "description": "How many results to return, best first. Default: every document." }, "return_documents": { "type": "boolean", "default": false, "description": "Attach each result's document text (the text you sent)." }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" } } }, "RerankResult": { "type": "object", "required": [ "index", "relevance_score" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Position of the document in the request." }, "relevance_score": { "type": "number", "description": "The provider's score. The router checks it and never makes one up." }, "document": { "type": "object", "properties": { "text": { "type": "string" } }, "description": "Present when return_documents is true." } } }, "RerankResponse": { "type": "object", "required": [ "id", "model", "results", "usage", "cost", "receipt" ], "properties": { "id": { "type": "string", "description": "Generation and receipt id (also X-Receipt-Id)." }, "object": { "type": "string", "const": "rerank" }, "model": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RerankResult" }, "description": "Best first, ties by index, at most top_n." }, "usage": { "type": "object", "required": [ "total_tokens", "search_units", "cost" ], "properties": { "total_tokens": { "type": "integer" }, "search_units": { "type": "integer", "description": "One query over up to 100 documents, each split into chunks of 500 tokens." }, "estimated": { "type": "boolean", "description": "true when the provider did not report a quantity it is priced on and the router's estimate was billed." }, "cost": { "type": "number" }, "cost_details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "billed_units": { "type": "object", "properties": { "search_units": { "type": "integer" } } } }, "description": "The billed search units where Cohere clients read them." }, "cost": { "type": "number", "description": "USD charged for this call." }, "receipt": { "$ref": "#/components/schemas/Receipt" } } }, "Team": { "type": "object", "required": [ "id", "name", "created_at", "owner", "budget_usd", "allocated_usd", "your_role", "members", "principals", "audit" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "owner": { "type": "object", "required": [ "account", "address", "kind", "verified_at" ], "properties": { "account": { "type": "string" }, "address": { "type": [ "string", "null" ], "description": "The bound wallet or Safe, lowercase." }, "kind": { "type": "string", "enum": [ "account", "eoa", "contract" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "budget_usd": { "type": [ "number", "null" ], "description": "Org budget: a cap on the sum of the limits of the team's keys." }, "allocated_usd": { "type": "number", "description": "The limits of the team's enabled, unexpired keys, summed." }, "your_role": { "type": "string", "enum": [ "owner", "admin", "dev", "member", "viewer", "agent" ] }, "members": { "type": "array", "items": { "type": "object", "properties": { "key_hash": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "dev", "member", "viewer", "agent" ] }, "principal": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "disabled": { "type": "boolean" } } } }, "principals": { "type": "array", "items": { "$ref": "#/components/schemas/TeamPrincipal" } }, "audit": { "type": "object", "properties": { "entries": { "type": "integer" }, "head": { "type": "string", "description": "The chain's head hash (64 zeros when empty)." } } } } }, "TeamPrincipal": { "type": "object", "required": [ "id", "kind", "subject", "role", "disabled", "created_at", "last_used" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "passkey", "wallet" ] }, "subject": { "type": "string", "description": "A wallet address, or the first 16 characters of a passkey's credential id." }, "role": { "type": "string", "enum": [ "owner", "admin", "dev", "viewer" ] }, "disabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "last_used": { "type": [ "string", "null" ], "format": "date-time" } } }, "TeamInviteRequest": { "type": "object", "required": [ "role" ], "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "admin", "dev", "viewer" ], "description": "Agents are API keys (POST /api/v1/keys with role agent), not invited people. Only the owner invites an admin." }, "method": { "type": "string", "enum": [ "passkey", "wallet", "any" ], "default": "any" }, "ttl_hours": { "type": "integer", "minimum": 1, "maximum": 168, "default": 72 } } }, "TeamSignedIn": { "type": "object", "required": [ "data", "key" ], "properties": { "data": { "type": "object", "properties": { "team": { "type": "string" }, "principal": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "passkey", "wallet" ] }, "role": { "type": "string" } } }, "key": { "type": "object", "description": "The issued key (same shape as GET /api/v1/key): it expires after 12 hours and has a limit of 0." } } }, "key": { "type": "string", "description": "The secret, shown once." } } }, "TeamAuditEntry": { "type": "object", "required": [ "team", "seq", "at", "actor", "action", "target", "detail", "prev_hash", "hash" ], "properties": { "team": { "type": "string" }, "seq": { "type": "integer", "minimum": 1 }, "at": { "type": "string", "format": "date-time" }, "actor": { "type": "string", "description": "key:<16 hex>, passkey: or wallet:
." }, "action": { "type": "string", "enum": [ "team.create", "team.rename", "budget.set", "owner.bind", "invite.create", "member.join", "member.role", "member.revoke", "member.restore", "key.create", "key.update", "key.disable", "preset.save", "preset.rollback", "preset.delete", "route.create", "route.update", "route.delete" ] }, "target": { "type": "string" }, "detail": { "type": "object", "description": "A few fixed fields about the change (role, limit, lane, version, hash). Never prompt text." }, "prev_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256(bytes(prev_hash) || utf8(canonical JSON of {team, seq, at, actor, action, target, detail})), keys sorted recursively." } } }, "TeamAuditRoot": { "type": "object", "required": [ "hour", "first_seq", "last_seq", "count", "root" ], "properties": { "hour": { "type": "string", "format": "date-time" }, "first_seq": { "type": "integer" }, "last_seq": { "type": "integer" }, "count": { "type": "integer" }, "root": { "type": "string", "description": "RFC 6962 Merkle root over the raw 32-byte entry hashes of that UTC hour." } } }, "WalletChallenge": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "nonce": { "type": "string" }, "method": { "type": "string" }, "message": { "type": "string", "description": "Sign with personal_sign (EOA) or through the Safe (EIP-1271)." }, "expires_at": { "type": "string", "format": "date-time" } } }, "TeamChallenge": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "method": { "type": "string", "enum": [ "passkey", "wallet" ] }, "message": { "type": "string", "description": "Wallet: the message to sign." }, "publicKey": { "type": "object", "description": "Passkey: WebAuthn options with base64url binary fields (PublicKeyCredentialCreationOptions to join, PublicKeyCredentialRequestOptions to sign in). Attestation is none; sign-in uses discoverable passkeys and lists no credentials." }, "expires_at": { "type": "string", "format": "date-time" } } }, "StatusIncident": { "type": "object", "required": [ "id", "title", "status", "impact", "lanes", "surfaces", "source", "started_at", "resolved_at", "updated_at", "updates" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "suggested", "investigating", "identified", "monitoring", "resolved", "dismissed" ], "description": "suggested and dismissed are seen only by the operator." }, "impact": { "type": "string", "enum": [ "none", "minor", "major", "critical" ] }, "lanes": { "type": "array", "items": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] }, "minItems": 1 }, "surfaces": { "type": "array", "items": { "type": "string", "enum": [ "chat", "embeddings", "batch", "messages", "ollama", "rerank" ] }, "description": "Empty for all surfaces." }, "source": { "type": "string", "enum": [ "operator", "auto" ] }, "started_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "updates": { "type": "array", "description": "Newest first.", "items": { "type": "object", "required": [ "at", "status", "text" ], "properties": { "at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "text": { "type": "string" } } } }, "evidence": { "type": "object", "description": "Automatic suggestions only: lanes, surfaces, window (5m for the public lane, 1h for the private lanes), availability, target, requests and source (request-aggregates or dp-noised)." } } }, "StatusSlo": { "type": "object", "required": [ "object", "generated_at", "windows", "targets", "lanes", "surfaces", "incidents" ], "properties": { "object": { "const": "status.slo" }, "generated_at": { "type": "string", "format": "date-time" }, "cache_seconds": { "type": "integer" }, "windows": { "type": "array", "items": { "type": "string", "enum": [ "1h", "24h", "7d", "30d" ] } }, "targets": { "type": "object", "description": "Availability target per lane, as a fraction (STATUS_SLO_PUBLIC 0.995, STATUS_SLO_ATTESTED 0.99, STATUS_SLO_UNLINKABLE 0.99)." }, "lanes": { "type": "array", "items": { "type": "object", "required": [ "lane", "source", "target", "state", "windows", "latency_24h", "error_budget", "daily" ], "properties": { "lane": { "type": "string", "enum": [ "public", "attested", "unlinkable" ] }, "source": { "type": "string", "enum": [ "request-aggregates", "dp-noised" ], "description": "dp-noised: every figure is summed from the differentially private hourly releases, never from per-request records." }, "target": { "type": "number" }, "state": { "type": "string", "enum": [ "operational", "degraded", "outage", "no_data" ] }, "scope": { "type": "string", "description": "Private lanes: attested+unlinkable, because the two lanes share one set of noisy counters." }, "windows": { "type": "object", "description": "Per window (1h, 24h, 7d, 30d): availability (null without enough data), eligible requests (5xx and successes; 4xx and 429 are left out) and error counts by class." }, "latency_24h": { "type": "object", "description": "p50_ms and p95_ms as the upper edge of the fixed latency bucket each falls in. Public lane: time to first token for streams, full response otherwise. Private lanes: total generation time, the only latency the noisy counters keep." }, "error_budget": { "type": "object", "description": "Over 30 days: allowed_failures, failures, remaining (share of the budget unspent) and exhausted." }, "daily": { "type": "array", "description": "90 UTC days, oldest first: availability (null without data) and eligible requests.", "items": { "type": "object" } }, "privacy": { "type": "object", "description": "Private lanes: mechanism, epsilon per hour, noise scale and the minimum noisy eligible count before a share is shown." } } } }, "surfaces": { "type": "array", "description": "Per API surface, public lane only. rerank appears only where the router serves it.", "items": { "type": "object" } }, "synthetic_24h": { "type": "object", "description": "Provider probes and canaries over 24 hours." }, "incidents": { "type": "object", "properties": { "open": { "type": "array", "items": { "$ref": "#/components/schemas/StatusIncident" } }, "recent": { "type": "array", "items": { "$ref": "#/components/schemas/StatusIncident" } } } } } }, "CharacterCard": { "type": "object", "description": "A Tavern character card in its canonical form. card_hash is the SHA-256 of this object as canonical JSON.", "required": [ "spec", "spec_version", "data" ], "properties": { "spec": { "type": "string", "enum": [ "chara_card_v2", "chara_card_v3" ] }, "spec_version": { "type": "string", "examples": [ "2.0", "3.0" ] }, "data": { "type": "object", "description": "The card's fields as the Tavern character card V2 and V3 specs define them. A V1 card (flat fields) is read as V2. Fields the router does not use are kept as they are.", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "personality": { "type": "string" }, "scenario": { "type": "string" }, "first_mes": { "type": "string", "description": "The first greeting (greeting index 0)." }, "mes_example": { "type": "string" }, "system_prompt": { "type": "string" }, "post_history_instructions": { "type": "string" }, "alternate_greetings": { "type": "array", "items": { "type": "string" }, "description": "Greetings 1, 2, 3 and so on." }, "tags": { "type": "array", "items": { "type": "string" } }, "creator": { "type": "string" }, "creator_notes": { "type": "string" }, "character_version": { "type": "string" }, "character_book": { "type": "object", "description": "The lorebook: entries with keys and content." }, "extensions": { "type": "object" } } } } }, "Character": { "type": "object", "required": [ "id", "model", "visibility", "name", "tags", "creator", "spec", "card_hash", "default_model", "owner", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "model": { "type": "string", "description": "The model id that calls this character: @character/." }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ], "description": "public: listed in discovery and readable by anyone. unlisted: readable by anyone with the id, not listed. private: sealed on the owner's device; only the owner can read it." }, "name": { "type": [ "string", "null" ], "description": "null for a private card: the router never sees it." }, "tags": { "type": "array", "items": { "type": "string" } }, "creator": { "type": [ "string", "null" ] }, "spec": { "type": [ "string", "null" ], "enum": [ "chara_card_v2", "chara_card_v3", null ], "description": "null for a private card." }, "card_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the canonical card JSON. For a private card the client computes it before sealing, and a chat call's decrypted card is checked against it." }, "default_model": { "type": [ "string", "null" ], "description": "The model that answers when a call names none (no models[0])." }, "card": { "$ref": "#/components/schemas/CharacterCard", "description": "Public and unlisted cards only." }, "sealed_card": { "type": "string", "description": "Private cards, to the owner only: the card encrypted on the owner's device (arm1..). The router cannot read it." }, "owner": { "type": "boolean", "description": "true when the calling key owns this card." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CharacterInput": { "type": "object", "additionalProperties": false, "description": "Send the card as JSON (card) or as a PNG that carries it (png). A private card is sealed on the client instead: send sealed_card and card_hash, never the plaintext.", "properties": { "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ], "default": "unlisted" }, "card": { "type": "object", "description": "A Tavern character card: V1 (flat fields), V2 (chara_card_v2) or V3 (chara_card_v3) JSON." }, "png": { "type": "string", "contentEncoding": "base64", "description": "A PNG, base64, that carries the card in a ccv3 or chara tEXt chunk (ccv3 wins when both are present)." }, "model": { "type": "string", "description": "The default model for @character/." }, "sealed_card": { "type": "string", "description": "Private only: the card encrypted on the client (sealCard in @anyroute/client/characters). The router stores it as it is and never sees the plaintext." }, "card_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Private only: the SHA-256 of the canonical card JSON, computed before sealing." } } }, "CharacterChatRequest": { "description": "A chat completions request plus the character options. The character's prompt is built by the router from the card; lanes, budgets and receipts apply as on /chat/completions. model, when set, is the model that answers; otherwise models[0], then the card's default model.", "allOf": [ { "$ref": "#/components/schemas/ChatRequest" }, { "type": "object", "properties": { "session_id": { "type": "string", "description": "Your own id for a conversation, so regenerate knows which turn to redo." }, "greeting": { "type": "integer", "minimum": 0, "description": "Which greeting opens the chat: 0 is first_mes, 1 and up are alternate_greetings." }, "regenerate": { "type": "boolean", "description": "Answer the last user turn again." }, "user_name": { "type": "string", "description": "Replaces {{user}} in the card." }, "memory": { "type": "object", "description": "Memory the client decrypted from its ledger. Used for this call, in memory only, and never stored.", "properties": { "summary": { "type": "string" }, "facts": { "type": "array", "items": { "type": "string" } } } }, "card": { "type": "object", "description": "Private cards only: the card decrypted on the client. It must hash to the character's card_hash, or the call is refused." } } } ] }, "CharacterUsage": { "type": "object", "required": [ "period", "calls", "cost_usd" ], "properties": { "period": { "type": "string", "format": "date", "description": "YYYY-MM-DD" }, "calls": { "type": "integer" }, "cost_usd": { "type": "number" } } }, "CharacterGroupNextRequest": { "type": "object", "additionalProperties": false, "required": [ "members", "messages" ], "properties": { "members": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^ch_[0-9a-f]{24}$" }, "description": "The characters in the group chat, in order." }, "mode": { "type": "string", "enum": [ "round_robin", "named" ], "default": "round_robin", "description": "round_robin: the next member after the last speaker. named: the member the last message names, else round robin." }, "messages": { "type": "array", "items": { "type": "object" }, "description": "The chat so far, as chat completions messages; an assistant message's name is the character that spoke." } } }, "MemoryInput": { "type": "object", "additionalProperties": false, "required": [ "scope", "kind", "sealed", "key_id" ], "properties": { "scope": { "type": "string", "pattern": "^[0-9a-f]{16,128}$", "description": "Derived on the client: an HMAC of the character id under the viewing key, so the router cannot tell which character a memory belongs to." }, "kind": { "type": "string", "enum": [ "summary", "fact", "lorebook", "state" ] }, "sealed": { "type": "string", "pattern": "^arm1\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "arm1.., encrypted on the client. The router stores only this." }, "key_id": { "type": "string", "pattern": "^[0-9a-f]{16}$", "description": "Which of the client's keys sealed it." }, "embedding": { "type": "array", "items": { "type": "number" }, "description": "Stored only with embedding_opt_in: true." }, "embedding_opt_in": { "const": true, "description": "Store the embedding for POST /api/v1/memory/search. Off by default: a vector is derived from the memory's text and can leak its topic." } } }, "MemoryEntry": { "type": "object", "required": [ "id", "scope", "kind", "key_id", "bytes", "has_embedding", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "scope": { "type": "string" }, "kind": { "type": "string", "enum": [ "summary", "fact", "lorebook", "state" ] }, "key_id": { "type": "string" }, "bytes": { "type": "integer", "description": "Size of the sealed value." }, "has_embedding": { "type": "boolean" }, "dims": { "type": [ "integer", "null" ] }, "sealed": { "type": "string", "description": "Only when one entry is read (GET /api/v1/memory/{id})." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MemorySearchRequest": { "type": "object", "additionalProperties": false, "required": [ "scope", "embedding" ], "properties": { "scope": { "type": "string" }, "embedding": { "type": "array", "items": { "type": "number" } }, "k": { "type": "integer", "minimum": 1, "maximum": 50, "default": 5 } } }, "SkillFinding": { "type": "object", "required": [ "rule", "file", "line", "excerpt", "severity", "message" ], "properties": { "rule": { "type": "string", "description": "Rule id, e.g. exfil.env_to_network, injection.override, obfuscation.base64_blob, shell.rm_root, deps.untrusted_index, binary.executable." }, "file": { "type": "string" }, "line": { "type": [ "integer", "null" ] }, "excerpt": { "type": "string", "description": "Up to 160 characters of the line, with hidden characters shown escaped." }, "severity": { "type": "string", "enum": [ "info", "low", "medium", "high", "critical" ] }, "message": { "type": "string" } } }, "SkillScanReport": { "type": "object", "required": [ "scanner", "score", "level", "summary", "findings", "note" ], "properties": { "scanner": { "type": "string", "example": "skillscan/1" }, "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "100 minus a weight per distinct rule and file: low 3, medium 10, high 25, critical 50." }, "level": { "type": "string", "enum": [ "trusted", "caution", "dangerous" ], "description": "dangerous with any high or critical finding or a score under 40; caution with any medium finding or a score under 90; trusted otherwise." }, "summary": { "type": "object", "additionalProperties": { "type": "integer" } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/SkillFinding" } }, "truncated": { "type": "boolean" }, "files_scanned": { "type": "integer" }, "bytes_scanned": { "type": "integer" }, "note": { "type": "string", "description": "Scanned, not guaranteed." } } }, "SkillSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "author": { "type": "string" }, "content_hash": { "type": "string", "description": "sha256 (hex) of the canonical tar of the skill's files." }, "level": { "type": "string", "enum": [ "trusted", "caution", "dangerous" ] }, "score": { "type": "integer" }, "findings": { "type": "object", "additionalProperties": { "type": "integer" } }, "price_usd": { "type": "number" }, "files": { "type": "integer" }, "size": { "type": "integer" }, "source": { "type": "string", "enum": [ "upload", "git", "mirror" ] }, "revoked": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Skill": { "allOf": [ { "$ref": "#/components/schemas/SkillSummary" }, { "type": "object", "properties": { "manifest": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "author": { "type": "string" } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "symlink" ] }, "mode": { "type": "integer" }, "size": { "type": "integer" }, "sha256": { "type": "string" } } } }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "upload", "git", "mirror" ] }, "repo": { "type": "string" }, "ref": { "type": "string" }, "commit": { "type": "string" }, "path": { "type": "string" }, "registry": { "type": "string" } } }, "scan": { "$ref": "#/components/schemas/SkillScanReport" }, "downloadable": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_reason": { "type": [ "string", "null" ] }, "installs": { "type": "integer" }, "chain": { "type": "object", "description": "Arguments for SkillRegistry.publish(skillHash, author, priceUSDG, trustLevel, uri).", "properties": { "skill_hash": { "type": "string" }, "trust_level": { "type": "integer", "enum": [ 1, 2, 3 ] }, "price_usdg": { "type": "string" }, "uri": { "type": "string" } } } } } ] }, "SkillInstall": { "type": "object", "properties": { "id": { "type": "string" }, "skill_id": { "type": "string" }, "price_usd": { "type": "number" }, "author_usd": { "type": "number" }, "fee_usd": { "type": "number" }, "download_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "receipt": { "type": "object", "description": "Ed25519 signature (receipt key) over the canonical JSON of payload.", "properties": { "payload": { "type": "object" }, "signature": { "type": "object", "properties": { "alg": { "type": "string", "enum": [ "Ed25519" ] }, "key_id": { "type": "string" }, "sig": { "type": "string" } } } } } } }, "HostPolicy": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "issued_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "tee_kinds": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "tdx", "snp", "nvidia-cc" ] } }, "sidecar": { "type": "object", "properties": { "image_digests": { "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" } }, "source_hashes": { "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" } } }, "required": [ "image_digests", "source_hashes" ], "additionalProperties": false }, "engines": { "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$" }, "image_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" } }, "required": [ "name", "image_digest" ], "additionalProperties": false } }, "models": { "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$" }, "model_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "offer": { "$ref": "#/components/schemas/HostPolicyOffer" }, "min_gpu_cc": { "type": "boolean" } }, "required": [ "id", "model_digest", "min_gpu_cc" ], "additionalProperties": false } }, "rules": { "type": "object", "properties": { "require_gpu_cc_for": { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$" } }, "allow_dev": { "type": "boolean", "const": false } }, "required": [ "require_gpu_cc_for", "allow_dev" ], "additionalProperties": false } }, "required": [ "version", "issued_at", "tee_kinds", "sidecar", "engines", "models", "rules" ], "additionalProperties": false }, "HostPolicyOffer": { "type": "object", "additionalProperties": false, "required": [ "slug", "name", "context_length", "max_completion_tokens", "pricing" ], "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "hugging_face_id": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$" }, "context_length": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "max_completion_tokens": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "quantization": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9._+-]+$" }, "pricing": { "type": "object", "additionalProperties": false, "required": [ "prompt", "completion" ], "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Positive decimal USD per token, at most 1000000." }, "completion": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Positive decimal USD per token, at most 1000000." } } } } }, "HostPolicyPublication": { "type": "object", "required": [ "policy", "canonical", "sha256", "signature", "transparency_log" ], "properties": { "policy": { "$ref": "#/components/schemas/HostPolicy" }, "canonical": { "type": "string", "description": "Exact UTF-8 canonical policy bytes: sorted object keys, retained array order, no whitespace or trailing newline." }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "signature": { "type": "object", "required": [ "alg", "value", "verifier_key" ], "properties": { "alg": { "const": "Ed25519" }, "value": { "type": "string", "description": "Base64 detached Ed25519 signature over canonical UTF-8 bytes." }, "verifier_key": { "type": "string", "description": "C2SP signed-note verifier key. Pin independently; this response alone does not authenticate the operator." } } }, "transparency_log": { "type": "object", "required": [ "kind", "proof_url" ], "properties": { "kind": { "const": "host_policy" }, "proof_url": { "type": "string", "description": "Inclusion proof under a signed checkpoint; independent checkpoint checks are separate." } } } } }, "AgentRecordClaims": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^(requests_at_least|active_days_at_least|no_denials_days|no_kills_days):[1-9][0-9]{0,14}$" }, "description": "Positive integer thresholds. Absence windows are at most 90 days and require an unchanged effective rulebook for the full interval. Counts use the calling key’s retained completed non-cancelled generations; active days are distinct UTC dates. No autonomy rung claim is available." }, "AgentRecordCertificate": { "type": "object", "additionalProperties": false, "required": [ "payload", "key_id", "signature" ], "properties": { "key_id": { "type": "string", "pattern": "^[0-9a-f]{16}$" }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "type", "pseudonym", "claims", "issued_at", "expires_at", "notice" ], "properties": { "version": { "const": 1 }, "type": { "const": "anyroute.agent.record-certificate" }, "pseudonym": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "claims": { "$ref": "#/components/schemas/AgentRecordClaims" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Exactly seven days after issuance." }, "notice": { "const": "Signed by AnyRoute's router, which sees the agent's activity; not a zero-knowledge proof." } } } } }, "ToolCallRequest": { "type": "object", "required": [ "resource", "max_price" ], "additionalProperties": false, "properties": { "resource": { "type": "string", "maxLength": 2048, "description": "The tool's https address, with its query arguments. Only the origin and path are stored." }, "method": { "type": "string", "enum": [ "GET", "POST" ], "default": "GET" }, "body": { "description": "JSON sent to the tool as a POST body, at most 64 KiB." }, "max_price": { "oneOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "string", "pattern": "^[0-9]{1,7}(\\.[0-9]{1,12})?$" } ], "description": "The most this call may charge the key in USD: the seller's price plus the router's take." }, "then": { "type": "object", "required": [ "model" ], "additionalProperties": false, "description": "Hand the answer to a model in the same call; needs tools.pass_to_models.", "properties": { "model": { "type": "string" }, "prompt": { "type": "string", "maxLength": 4000 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 8192 } } } } }, "ToolCall": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "ok" ] }, "resource": { "type": "string" }, "method": { "type": "string" }, "seller": { "type": "object", "properties": { "pay_to": { "type": "string" }, "seller_id": { "type": [ "string", "null" ] }, "network": { "type": "string" } } }, "x402_version": { "type": "integer", "enum": [ 1, 2 ] }, "price_usd": { "type": "number" }, "take_usd": { "type": "number" }, "charged_usd": { "type": "number" }, "settle": { "type": "object", "properties": { "tx": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] } } }, "response": { "type": "object", "description": "The tool's answer, untrusted: json or text, with status, content_type, bytes and sha256.", "properties": { "status": { "type": "integer" }, "content_type": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "untrusted": { "type": "boolean" }, "json": {}, "text": { "type": "string" } } }, "receipt": { "type": "object", "description": "kind tool.call: COSE_Sign1 (base64) under the receipt key, key_id, leaf and the signed claims.", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "tool.call" ] }, "key_id": { "type": "string" }, "cose": { "type": "string" }, "leaf": { "type": "string" }, "claims": { "type": "object" } } }, "model": { "type": "object", "description": "Present when then was set." } } }, "ToolListing": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "summary": { "type": "string" }, "resource": { "type": "string" }, "method": { "type": "string" }, "price_usd": { "type": [ "number", "null" ] }, "price_units": { "type": [ "string", "null" ] }, "pay_to": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "listing", "skill", "facilitator", "public_catalog" ] }, "skill_id": { "type": [ "string", "null" ] }, "quality": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "passing", "failing", "delisted", "unchecked" ] }, "consecutive_failures": { "type": "integer" }, "checked_at": { "type": [ "string", "null" ] }, "delisted_at": { "type": [ "string", "null" ] } } } } }, "ToolListingRequest": { "type": "object", "required": [ "name", "summary", "resource", "canary" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 80 }, "summary": { "type": "string", "maxLength": 280 }, "resource": { "type": "string", "description": "https address without a query string." }, "method": { "type": "string", "enum": [ "GET", "POST" ], "default": "GET" }, "skill_id": { "type": "string", "pattern": "^sk_[0-9a-f]{24}$" }, "canary": { "type": "object", "required": [ "expect" ], "additionalProperties": false, "properties": { "query": { "type": "string" }, "body": {}, "expect": { "type": "object", "description": "Exactly one of contains or sha256.", "properties": { "contains": { "type": "string", "maxLength": 200 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } } }, "CommerceStats": { "type": "object", "required": [ "as_of", "cache_seconds", "currency", "kinds", "filters", "windows", "methodology_url", "dune_query" ], "properties": { "as_of": { "type": "string", "format": "date-time" }, "cache_seconds": { "type": "integer", "const": 60 }, "currency": { "type": "object", "properties": { "asset": { "type": "string", "const": "USDG" }, "decimals": { "type": "integer", "const": 6 }, "units": { "type": "string" } } }, "kinds": { "type": "array", "items": { "type": "object", "required": [ "kind", "label", "wired" ], "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "wired": { "type": "boolean", "description": "Whether anything reports settlements of this kind to the ledger" } } } }, "filters": { "type": "object", "properties": { "anchored_only": { "type": "boolean", "const": true }, "same_owner": { "type": "boolean", "const": true }, "round_trip_hours": { "type": "integer", "const": 24 }, "funding": { "type": "object", "required": [ "available", "hops", "min_units", "hub_fanout", "from_block", "indexed_block", "indexed_at" ], "properties": { "available": { "type": "boolean" }, "hops": { "type": "integer", "minimum": 1, "maximum": 3 }, "min_units": { "type": "string", "pattern": "^[0-9]+$" }, "hub_fanout": { "type": "integer", "minimum": 1 }, "from_block": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "indexed_block": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "indexed_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "windows": { "type": "object", "required": [ "24h", "7d", "30d" ], "properties": { "24h": { "$ref": "#/components/schemas/CommerceWindow" }, "7d": { "$ref": "#/components/schemas/CommerceWindow" }, "30d": { "$ref": "#/components/schemas/CommerceWindow" } } }, "methodology_url": { "type": "string" }, "dune_query": { "type": "string" } } }, "CommerceWindow": { "type": "object", "required": [ "from", "to", "total", "kinds" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "total": { "$ref": "#/components/schemas/CommerceBlock" }, "kinds": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CommerceBlock" } } } }, "CommerceBlock": { "type": "object", "required": [ "gross", "filtered", "excluded" ], "properties": { "gross": { "$ref": "#/components/schemas/CommerceFigures" }, "filtered": { "$ref": "#/components/schemas/CommerceFigures" }, "excluded": { "type": "object", "required": [ "unanchored", "same_owner", "round_trip", "funding_link" ], "properties": { "unanchored": { "type": "integer", "minimum": 0 }, "same_owner": { "type": "integer", "minimum": 0 }, "round_trip": { "type": "integer", "minimum": 0 }, "funding_link": { "type": "integer", "minimum": 0 } }, "description": "Each excluded settlement is counted once, under the first rule it fails" } } }, "CommerceFigures": { "type": "object", "required": [ "settlements", "payers", "payees", "volume_usdg", "median_price_usdg", "refunds", "refund_rate" ], "properties": { "settlements": { "type": "integer", "minimum": 0 }, "payers": { "type": "integer", "minimum": 0 }, "payees": { "type": "integer", "minimum": 0 }, "volume_usdg": { "type": "string", "pattern": "^[0-9]+$" }, "median_price_usdg": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "The middle amount, or the floor of the mean of the two middle amounts; null when there are none" }, "refunds": { "type": "integer", "minimum": 0 }, "refund_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Refunded over settlements, to four decimals; null when there are none" } } }, "DataToolCharge": { "type": "object", "required": [ "usd", "paid_with", "payment_tx" ], "properties": { "usd": { "type": "string", "description": "What this call was charged, in USD (DATA_TOOLS_PRICE_USD, default 0.001)." }, "paid_with": { "type": "string", "enum": [ "key", "per_call" ] }, "payment_tx": { "type": [ "string", "null" ], "description": "The settling transaction of a per-call payment; null for a key." } } }, "DataToolsIndex": { "type": "object", "properties": { "price_usd": { "type": "number" }, "payment": { "type": "object", "properties": { "prepaid_key": { "type": "boolean" }, "x402": { "type": "boolean" }, "callpay": { "type": "boolean" } } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" } } } }, "symbols": { "type": "array", "items": { "type": "string" } }, "ipx_classes": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } }, "DataStockPrice": { "type": "object", "required": [ "object", "symbol", "token", "price_usd", "price_e18", "source", "multiplier", "status", "read_at" ], "properties": { "object": { "type": "string", "const": "data.stock_price" }, "symbol": { "type": "string" }, "token": { "type": "string" }, "chain_id": { "type": "integer" }, "price_usd": { "type": "string", "description": "USD per whole Stock Token, decimal string." }, "price_e18": { "type": "string" }, "unit": { "type": "string" }, "source": { "type": "object", "properties": { "kind": { "type": "string", "const": "chainlink" }, "feed": { "type": "string" }, "decimals": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "age_seconds": { "type": "integer" }, "max_age_seconds": { "type": "integer" } } }, "multiplier": { "allOf": [ { "type": "object", "properties": { "ui_multiplier": { "type": [ "string", "null" ], "description": "Decimal, 18 decimals of precision." }, "ui_multiplier_raw": { "type": [ "string", "null" ] }, "scheduled": { "type": [ "object", "null" ], "properties": { "ui_multiplier": { "type": "string" }, "ui_multiplier_raw": { "type": "string" }, "effective_at": { "type": "string", "format": "date-time" }, "in_effect": { "type": "boolean" } } }, "pending_change": { "type": "boolean" } } }, { "type": "object", "properties": { "included_in_price": { "type": "boolean", "const": true } } } ] }, "status": { "type": "object", "properties": { "paused": { "type": [ "boolean", "null" ] }, "oracle_paused": { "type": [ "boolean", "null" ] } } }, "read_at": { "type": "string", "format": "date-time" } } }, "DataStockActions": { "allOf": [ { "type": "object", "properties": { "ui_multiplier": { "type": [ "string", "null" ], "description": "Decimal, 18 decimals of precision." }, "ui_multiplier_raw": { "type": [ "string", "null" ] }, "scheduled": { "type": [ "object", "null" ], "properties": { "ui_multiplier": { "type": "string" }, "ui_multiplier_raw": { "type": "string" }, "effective_at": { "type": "string", "format": "date-time" }, "in_effect": { "type": "boolean" } } }, "pending_change": { "type": "boolean" } } }, { "type": "object", "properties": { "object": { "type": "string", "const": "data.stock_actions" }, "symbol": { "type": "string" }, "token": { "type": "string" }, "chain_id": { "type": "integer" }, "price_feed_includes_multiplier": { "type": "boolean" }, "status": { "type": "object", "properties": { "paused": { "type": [ "boolean", "null" ] }, "oracle_paused": { "type": [ "boolean", "null" ] }, "price_served": { "type": "boolean" } } }, "note": { "type": "string" }, "read_at": { "type": "string", "format": "date-time" } } } ] }, "DataIpx": { "type": "object", "description": "The IPX snapshot of GET /api/v1/ipx/{class} with object data.ipx.", "properties": { "object": { "type": "string", "const": "data.ipx" }, "class": { "type": "string" }, "unit": { "type": "string" }, "decimals": { "type": "integer" }, "price": { "type": "string" }, "price_e8": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "thin": { "type": "boolean" }, "volume_usdg_24h": { "type": "string" }, "fills_24h": { "type": "integer" }, "receipt_root": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "ProjectBudget": { "type": "object", "required": [ "name", "month", "spent_usd", "held_usd", "budget_usd" ], "properties": { "name": { "type": "string" }, "month": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" }, "spent_usd": { "type": "string", "description": "Decimal USD amount" }, "held_usd": { "type": "string", "description": "Decimal USD amount" }, "budget_usd": { "type": [ "string", "null" ], "description": "Monthly cap in USD; null means absent" } } }, "ProjectBudgetExceeded": { "type": "object", "description": "Inference refuses before contacting a provider when project charged spend plus pending holds and the request estimate exceeds its monthly budget. Nothing is charged.", "properties": { "error": { "type": "object", "properties": { "type": { "const": "project_budget_exceeded" }, "message": { "type": "string" }, "metadata": { "type": "object", "properties": { "project": { "type": "string" }, "month": { "type": "string" }, "budget_usd": { "type": "string" }, "spent_usd": { "type": "string" }, "held_usd": { "type": "string" } } } } } } } } }, "x-idempotency": { "card": "D145", "documentation": "/docs/#idempotency", "ttl_seconds": 86400, "auth": "current API key and usual inference role; Messages also accepts x-api-key", "replay_header": "Idempotent-Replay: true", "409": "idempotency_in_progress or idempotency_result_not_kept with original receipt_id when available", "422": "idempotency_key_reused", "503": "idempotency_unavailable; new protected call refused before billing", "streams": "not kept; completed retries return 409 with original receipt id" }, "x-project-budget-refusal": { "$ref": "#/components/schemas/ProjectBudgetExceeded" }, "x-anyroute-agent-approvers": { "card": "E153", "flag": "AGENT_TEAM_APPROVERS_ENABLED", "default": false, "documentation": "/docs/#approvers", "existing_routes": { "GET /api/v1/agents": "Allowed member/dev keys see only approvable agents; those rows add approval_only=true and remain read-only for rulebook management.", "GET /api/v1/agents/approvals": "Lists allowed agents. Adds can_allow boolean to approval rows when enabled.", "POST /api/v1/agents/approvals/{id}/approve and /deny": "Allowed approvers, account/team scoped. Permission rechecked in existing locked single-use transaction. decided_by stores deciding key hash.", "GET /api/v1/inbox": "Adds delegated pending approvals with can_decide=true. Non-management approvers with actionable requests use scope=team_approvals; other sources remain key-scoped.", "GET/POST/DELETE /api/v1/telegram/link": "Allowed approvers may link their own Telegram; callback authorization matches API decisions. Other notifications and Stop remain owner/admin guarded." } }, "x-j177-account-checkup": { "documentation": "/docs/#account-checkup", "endpoint": null, "flag": null, "description": "Browser composition of existing authenticated GET /api/v1/key, /api/v1/keys, /api/v1/agents, /api/v1/telegram/link, /api/v1/account/low-balance, /api/v1/account/security-alerts and /api/v1/account/notifications. Existing guards and feature switches apply; failed reads remain unavailable. Read-only keys are refused by the checkup reader; the GET allow-list is unchanged. No new endpoint, fields, server storage or automatic action. Fix opens existing controls. Dismissed item ids and public key hashes stay in browser localStorage. Used management keys without an IP list get a suggestion; existing APIs provide no count of usage locations. Optional business details check omitted." } }