{ "openapi": "3.0.3", "info": { "title": "IIG — Internet Intelligence Gateway", "version": "v1", "description": "The OpenAI-wire inference router: four inference dialects over one routing/billing spine, token-exact billing against a nominal balance, and privacy tiers earned by provider policy citation. This document is generated from the router's own route registry — the same table GET /coverage serves — so it always matches the running wire. Unserved OpenAI-wire routes are not listed here: they refuse with the stable code not_supported, and GET /coverage names each one. Migrating from another router: GET /docs/migrate." }, "servers": [ { "url": "/", "description": "this router" } ], "tags": [ { "name": "Inference", "description": "The four wire dialects over one routing/billing spine: OpenAI chat completions, Anthropic Messages, OpenAI Responses, embeddings. class/\u003cname\u003e ids route by account class; iig/auto and friends are meta ids; :nitro/:floor suffixes pick the route sort." }, { "name": "Catalog", "description": "The model catalog: live effective prices, privacy tiers with policy citations, jurisdiction, the compact chooser payload, and the ZDR eligibility report." }, { "name": "Account \u0026 billing", "description": "Balance, accounting, per-generation billing metadata, top-ups, auto-refill, transfers, group buys, spend limits." }, { "name": "Keys \u0026 auth", "description": "API key lifecycle, identity-hook sessions, scoped browser keys, and the OAuth app flow." }, { "name": "BYOK", "description": "Bring-your-own provider keys: sealed at rest, dispatched without markup, metered like every other call." }, { "name": "Custom models", "description": "Account-scoped system-prompt wrappers over concrete catalog models." }, { "name": "Status", "description": "Liveness and the split-plane status surface (router core vs control plane)." }, { "name": "Meta", "description": "The router describing itself: the honest route coverage map, this document, the generated llms.txt / llms-full.txt agent-onboarding files, and the compliance packet — machine-readable procurement answers derived live from the deployment's configuration." }, { "name": "Pages", "description": "The embedded, self-contained browser pages (landing, security, console, playground, catalog, docs)." } ], "paths": { "/": { "get": { "operationId": "get_root", "summary": "GET /", "description": "the landing page (L1): what this router serves, linking onto the live surfaces (/models, /chat, /console, /security, /status)", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/.well-known/mcp.json": { "get": { "operationId": "get__well_known_mcp_json", "summary": "GET /.well-known/mcp.json", "description": "MCP discovery: the server card — endpoint, transport, auth style, protocol version, and the v1 tool list; public, every path same-origin relative", "tags": [ "Meta" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{file}": { "get": { "operationId": "get_assets_file", "summary": "GET /assets/{file}", "description": "embedded front-door css — served from the binary, self-contained (no external fetches)", "tags": [ "Pages" ], "parameters": [ { "name": "file", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "the embedded asset, served from the binary with its content type" } } } }, "/chat": { "get": { "operationId": "get_chat", "summary": "GET /chat", "description": "the chat playground (K5): public page — spending rides the session's scoped browser key (POST /v1/auth/browser-key) and streams through the public POST /v1/chat/completions SSE wire", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/chat/assets/{file}": { "get": { "operationId": "get_chat_assets_file", "summary": "GET /chat/assets/{file}", "description": "embedded playground css/js — served from the binary, self-contained (no external fetches)", "tags": [ "Pages" ], "parameters": [ { "name": "file", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "the embedded asset, served from the binary with its content type" } } } }, "/compliance.json": { "get": { "operationId": "get_compliance_json", "summary": "GET /compliance.json", "description": "the compliance packet (L4): machine-readable procurement answers scoped to what is TRUE for this deployment — subprocessors derived live from the configured providers (never a hand-maintained list), retention posture with citations, status/SLO pointers, contact (or its honest absence)", "tags": [ "Meta" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompliancePacket" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console": { "get": { "operationId": "get_console", "summary": "GET /console", "description": "the signed-in console shell (K1): session-gated server-side — no live session redirects to /console/signin; sections welcome (the A2 first-run onboarding flow) / keys / credits / activity / byok / settings", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/console/assets/{file}": { "get": { "operationId": "get_console_assets_file", "summary": "GET /console/assets/{file}", "description": "embedded console css/js — served from the binary, self-contained (no external fetches)", "tags": [ "Pages" ], "parameters": [ { "name": "file", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "the embedded asset, served from the binary with its content type" } } } }, "/console/signin": { "get": { "operationId": "get_console_signin", "summary": "GET /console/signin", "description": "the console sign-in page (public): posts the identity hook's credential to /v1/auth/signin", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/coverage": { "get": { "operationId": "get_coverage", "summary": "GET /coverage", "description": "this map", "tags": [ "Meta" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageMap" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/docs": { "get": { "operationId": "get_docs", "summary": "GET /docs", "description": "the API reference hub (L2): public — renders client-side from GET /openapi.json, so the page and the wire can never disagree; no CDN viewer, fully self-contained", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/docs/assets/{file}": { "get": { "operationId": "get_docs_assets_file", "summary": "GET /docs/assets/{file}", "description": "embedded docs css/js — served from the binary, self-contained (no external fetches)", "tags": [ "Pages" ], "parameters": [ { "name": "file", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "the embedded asset, served from the binary with its content type" } } } }, "/docs/migrate": { "get": { "operationId": "get_docs_migrate", "summary": "GET /docs/migrate", "description": "the migrate-from-other-routers one-pager (L2): base-URL swap, key format, class-mode + meta ids, the x-iig-* response headers", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/docs/routing": { "get": { "operationId": "get_docs_routing", "summary": "GET /docs/routing", "description": "the routing help page (A5): postures, privacy floors, provider preferences, and how to read GET /v1/route-preview's ladder + reason chain", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/health": { "get": { "operationId": "get_health", "summary": "GET /health", "tags": [ "Status" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leaderboard.json": { "get": { "operationId": "get_leaderboard_json", "summary": "GET /leaderboard.json", "description": "the provider leaderboard (J4): per-route p50/p95 TTFT, throughput, uptime and error rate — a synthetic lane (monitor cycles) and an observed lane (real traffic), clearly labeled; nearest-rank percentiles over bounded windows, and any stat backed by too few samples answers insufficient_data, never a fake number", "tags": [ "Status" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "get_llms_full_txt", "summary": "GET /llms-full.txt", "description": "the expanded llms.txt (L3): the index plus the essential wire documentation — inference request/response shapes from the OpenAPI schemas and the complete generated route list", "tags": [ "Meta" ], "responses": { "200": { "description": "the generated agent-onboarding text (markdown-shaped plain text; every link a same-origin relative path)", "content": { "text/plain": {} } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/llms.txt": { "get": { "operationId": "get_llms_txt", "summary": "GET /llms.txt", "description": "the agent-onboarding index (L3): what this router is, the key endpoints, where the spec and docs live — generated from this route table, every link same-origin", "tags": [ "Meta" ], "responses": { "200": { "description": "the generated agent-onboarding text (markdown-shaped plain text; every link a same-origin relative path)", "content": { "text/plain": {} } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "post": { "operationId": "post_mcp", "summary": "POST /mcp", "description": "the MCP server (streamable-HTTP transport, JSON-RPC 2.0, stateless): initialize / ping / tools/list / tools/call over an ordinary IIG bearer key. v1 tools are read + chat only — models-list, model-get, credits-get, generation-get, route-preview, docs-search, chat-send — each mapped onto the router's own wire (chat-send IS the chat door: same billing, same scoping); buffered JSON replies, no SSE frames; discovery at GET /.well-known/mcp.json", "tags": [ "Meta" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/models": { "get": { "operationId": "get_models", "summary": "GET /models", "description": "the model catalog page (K6): public — renders client-side from GET /v1/models (prices, privacy tiers with citation links, jurisdiction); #\u003cid\u003e deep-links a model row", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/models/assets/{file}": { "get": { "operationId": "get_models_assets_file", "summary": "GET /models/assets/{file}", "description": "embedded catalog css/js — served from the binary, self-contained (no external fetches)", "tags": [ "Pages" ], "parameters": [ { "name": "file", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "the embedded asset, served from the binary with its content type" } } } }, "/openapi.json": { "get": { "operationId": "get_openapi_json", "summary": "GET /openapi.json", "description": "the OpenAPI 3.0.3 document (L2), generated from this very route table — a served route missing from the spec is impossible by construction", "tags": [ "Meta" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/providers/marketplace/catalog.schema.json": { "get": { "operationId": "get_providers_marketplace_catalog_schema_json", "summary": "GET /providers/marketplace/catalog.schema.json", "description": "the provider marketplace contract (B7): the JSON Schema a would-be provider's catalog must conform to — public, so a candidate fetches the contract from any running router", "tags": [ "Meta" ], "responses": { "200": { "description": "the JSON Schema document (application/schema+json)", "content": { "application/schema+json": { "schema": { "type": "object", "description": "the B7 marketplace catalog contract" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/security": { "get": { "operationId": "get_security", "summary": "GET /security", "description": "the security/trust page (L1): every capability claim names the live endpoint that proves it (reproducible-build digests, /attestation nonce echo — always simulated:true, retention posture); unshipped work labeled roadmap", "tags": [ "Pages" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/status": { "get": { "operationId": "get_status", "summary": "GET /status", "description": "the human status page (J3): split SLO classes — router core vs control plane", "tags": [ "Status" ], "responses": { "200": { "description": "the embedded page (self-contained html)", "content": { "text/html": {} } } } } }, "/status.json": { "get": { "operationId": "get_status_json", "summary": "GET /status.json", "description": "machine status: per-class states + rolling windows over ingested monitor cycles + control-plane signals", "tags": [ "Status" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/status/history": { "get": { "operationId": "get_status_history", "summary": "GET /status/history", "description": "the bounded ring of past monitor cycles, newest first", "tags": [ "Status" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account": { "get": { "operationId": "get_v1_account", "summary": "GET /v1/account", "tags": [ "Account \u0026 billing" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/accounting": { "get": { "operationId": "get_v1_account_accounting", "summary": "GET /v1/account/accounting", "tags": [ "Account \u0026 billing" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/alerts": { "post": { "operationId": "post_v1_account_alerts", "summary": "POST /v1/account/alerts", "description": "spend alerts (A4): {webhookUrl?, secret?, lowBalanceUsd?, lowBalanceOff?} replaces the alert config wholesale; {} clears. Crossing 80%/100% of any window/cap or the low-balance line fires once per crossing per period - in the account's alerts view and, when configured, a signed metadata-only webhook POST", "tags": [ "Account \u0026 billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/authority": { "get": { "operationId": "get_v1_account_authority", "summary": "GET /v1/account/authority", "description": "the AUTHORITY balance (A1): the canister-held number the customer portal shows, proxied via the router's registered principal; local mode answers source 'local' — this router's ledger IS the authority there", "tags": [ "Account \u0026 billing" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/limits": { "post": { "operationId": "post_v1_account_limits", "summary": "POST /v1/account/limits", "description": "spend-window limits (E3): the body replaces the account's fixed UTC day/week/month caps wholesale; {} clears them", "tags": [ "Account \u0026 billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/preferences": { "post": { "operationId": "post_v1_account_preferences", "summary": "POST /v1/account/preferences", "tags": [ "Account \u0026 billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/provider-prefs": { "post": { "operationId": "post_v1_account_provider_prefs", "summary": "POST /v1/account/provider-prefs", "description": "default routing preferences (K4): the H2 routing block {order, only, ignore, allow_fallbacks, sort} stored per account and applied when a request carries none; {} clears", "tags": [ "Account \u0026 billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/refill": { "post": { "operationId": "post_v1_account_refill", "summary": "POST /v1/account/refill", "description": "auto-refill policy (E6): {thresholdUsd, amountUsd} — settles below threshold charge amount through the checkout seam, exactly once per crossing; {} disables", "tags": [ "Account \u0026 billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/topup": { "post": { "operationId": "post_v1_account_topup", "summary": "POST /v1/account/topup", "description": "top-up checkout via the adapter seam (E5); the dev adapter returns the signed webhook delivery", "tags": [ "Account \u0026 billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/account/transfer": { "post": { "operationId": "post_v1_account_transfer", "summary": "POST /v1/account/transfer", "description": "account-to-account credit transfer (E7): escrowed, exactly-once, idempotent by idempotencyKey; local mode only", "tags": [ "Account \u0026 billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/auth/browser-key": { "post": { "operationId": "post_v1_auth_browser_key", "summary": "POST /v1/auth/browser-key", "description": "the session's scoped browser key (D5): capped, expiring, rotating, inference-only", "tags": [ "Keys \u0026 auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ] } }, "/v1/auth/logout": { "post": { "operationId": "post_v1_auth_logout", "summary": "POST /v1/auth/logout", "description": "kills the session, clears the cookie", "tags": [ "Keys \u0026 auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ] } }, "/v1/auth/session": { "get": { "operationId": "get_v1_auth_session", "summary": "GET /v1/auth/session", "description": "the live session's envelope", "tags": [ "Keys \u0026 auth" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ] } }, "/v1/auth/signin": { "post": { "operationId": "post_v1_auth_signin", "summary": "POST /v1/auth/signin", "description": "sessions (D3): identity-hook sign-in mints the session cookie", "tags": [ "Keys \u0026 auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/byok/providers": { "get": { "operationId": "get_v1_byok_providers", "summary": "GET /v1/byok/providers", "description": "BYOK keys (G2): the caller's own stored provider keys — masked hints + route preference, never material; Features.BYOK-gated", "tags": [ "BYOK" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/byok/providers/{slug}": { "get": { "operationId": "get_v1_byok_providers_slug", "summary": "GET /v1/byok/providers/{slug}", "description": "PUT {key, prefer?} seals a provider key (G1 envelopes); usage_type 'byok' (or prefer) then dispatches with it — no markup, usage rows still meter; DELETE removes key + preference atomically", "tags": [ "BYOK" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] }, "put": { "operationId": "put_v1_byok_providers_slug", "summary": "PUT /v1/byok/providers/{slug}", "description": "PUT {key, prefer?} seals a provider key (G1 envelopes); usage_type 'byok' (or prefer) then dispatches with it — no markup, usage rows still meter; DELETE removes key + preference atomically", "tags": [ "BYOK" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] }, "delete": { "operationId": "delete_v1_byok_providers_slug", "summary": "DELETE /v1/byok/providers/{slug}", "description": "PUT {key, prefer?} seals a provider key (G1 envelopes); usage_type 'byok' (or prefer) then dispatches with it — no markup, usage rows still meter; DELETE removes key + preference atomically", "tags": [ "BYOK" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/chat/completions": { "post": { "operationId": "post_v1_chat_completions", "summary": "POST /v1/chat/completions", "description": "OpenAI chat wire; class/\u003cname\u003e ids route by class; :nitro/:floor id suffixes select the H7 route sort", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionsRequest" } } } }, "responses": { "200": { "description": "success; with body {\"stream\": true} the same operation answers text/event-stream in this dialect's event framing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } } }, "headers": { "x-iig-balance-microusd": { "description": "the account balance after settlement, micro-USD (buffered responses)", "schema": { "type": "string" } }, "x-iig-class": { "description": "the resolved class when the request rode a class/\u003cname\u003e id", "schema": { "type": "string" } }, "x-iig-cost-microusd": { "description": "what this call cost, micro-USD (buffered responses)", "schema": { "type": "string" } }, "x-iig-generation-id": { "description": "the generation id; resolve billing metadata via GET /v1/generation?id=", "schema": { "type": "string" } }, "x-iig-privacy-tier": { "description": "the retention tier the serving route earned by policy citation", "schema": { "type": "string" } }, "x-iig-provider-hq": { "description": "the serving provider's sourced headquarters country (absent when unknown)", "schema": { "type": "string" } }, "x-iig-usage-type": { "description": "'byok' when the call dispatched on a caller-stored provider key", "schema": { "type": "string" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/checkout/webhook": { "post": { "operationId": "post_v1_checkout_webhook", "summary": "POST /v1/checkout/webhook", "description": "processor webhook door: a verified delivery credits the balance exactly once per checkout id", "tags": [ "Account \u0026 billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/custom-models": { "get": { "operationId": "get_v1_custom_models", "summary": "GET /v1/custom-models", "description": "custom models (B6): the caller's account-scoped system-prompt wrappers over concrete chat models — 10 per account", "tags": [ "Custom models" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/custom-models/{slug}": { "get": { "operationId": "get_v1_custom_models_slug", "summary": "GET /v1/custom-models/{slug}", "description": "PUT {base, system_prompt} stores a wrapper (256 KiB prompt cap; base must be a chat catalog row — never class/meta/preset/custom ids); chatting with 'iig/user-{slug}' resolves to the base with the prompt prepended, billed at the base sheet", "tags": [ "Custom models" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] }, "put": { "operationId": "put_v1_custom_models_slug", "summary": "PUT /v1/custom-models/{slug}", "description": "PUT {base, system_prompt} stores a wrapper (256 KiB prompt cap; base must be a chat catalog row — never class/meta/preset/custom ids); chatting with 'iig/user-{slug}' resolves to the base with the prompt prepended, billed at the base sheet", "tags": [ "Custom models" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] }, "delete": { "operationId": "delete_v1_custom_models_slug", "summary": "DELETE /v1/custom-models/{slug}", "description": "PUT {base, system_prompt} stores a wrapper (256 KiB prompt cap; base must be a chat catalog row — never class/meta/preset/custom ids); chatting with 'iig/user-{slug}' resolves to the base with the prompt prepended, billed at the base sheet", "tags": [ "Custom models" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/embeddings": { "post": { "operationId": "post_v1_embeddings", "summary": "POST /v1/embeddings", "description": "input-only billing; \u003c= 16 inputs", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsRequest" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingList" } } }, "headers": { "x-iig-balance-microusd": { "description": "the account balance after settlement, micro-USD (buffered responses)", "schema": { "type": "string" } }, "x-iig-class": { "description": "the resolved class when the request rode a class/\u003cname\u003e id", "schema": { "type": "string" } }, "x-iig-cost-microusd": { "description": "what this call cost, micro-USD (buffered responses)", "schema": { "type": "string" } }, "x-iig-generation-id": { "description": "the generation id; resolve billing metadata via GET /v1/generation?id=", "schema": { "type": "string" } }, "x-iig-privacy-tier": { "description": "the retention tier the serving route earned by policy citation", "schema": { "type": "string" } }, "x-iig-provider-hq": { "description": "the serving provider's sourced headquarters country (absent when unknown)", "schema": { "type": "string" } }, "x-iig-usage-type": { "description": "'byok' when the call dispatched on a caller-stored provider key", "schema": { "type": "string" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/endpoints/zdr": { "get": { "operationId": "get_v1_endpoints_zdr", "summary": "GET /v1/endpoints/zdr", "description": "the ZDR eligibility report (F4): served routes at tier zdr or above, each with the policy citation that earned it", "tags": [ "Catalog" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/generation": { "get": { "operationId": "get_v1_generation", "summary": "GET /v1/generation", "description": "per-generation billing metadata (?id=, from x-iig-generation-id); bounded retention", "tags": [ "Account \u0026 billing" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/generation/content": { "get": { "operationId": "get_v1_generation_content", "summary": "GET /v1/generation/content", "description": "always answers content_not_stored — the router retains no transcripts", "tags": [ "Account \u0026 billing" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/groupbuys": { "get": { "operationId": "get_v1_groupbuys", "summary": "GET /v1/groupbuys", "description": "group-buy goals (E8): the aggregate view — totals, tier progress, opted-in public messages — plus the caller's own pledges", "tags": [ "Account \u0026 billing" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/groupbuys/{id}/pledge": { "post": { "operationId": "post_v1_groupbuys_id_pledge", "summary": "POST /v1/groupbuys/{id}/pledge", "description": "escrow balance toward a goal, idempotent by idempotencyKey; goal-met settles the tiers; local mode only", "tags": [ "Account \u0026 billing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/groupbuys/{id}/withdraw": { "post": { "operationId": "post_v1_groupbuys_id_withdraw", "summary": "POST /v1/groupbuys/{id}/withdraw", "description": "return an active pledge exactly (before goal-met); idempotent", "tags": [ "Account \u0026 billing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/keys": { "get": { "operationId": "get_v1_keys", "summary": "GET /v1/keys", "description": "key lifecycle (D2): GET lists, POST mints — key material shown once", "tags": [ "Keys \u0026 auth" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] }, "post": { "operationId": "post_v1_keys", "summary": "POST /v1/keys", "description": "key lifecycle (D2): GET lists, POST mints — key material shown once", "tags": [ "Keys \u0026 auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/keys/{hash}": { "patch": { "operationId": "patch_v1_keys_hash", "summary": "PATCH /v1/keys/{hash}", "description": "PATCH label/disable/spend cap, DELETE removes", "tags": [ "Keys \u0026 auth" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] }, "delete": { "operationId": "delete_v1_keys_hash", "summary": "DELETE /v1/keys/{hash}", "description": "PATCH label/disable/spend cap, DELETE removes", "tags": [ "Keys \u0026 auth" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/messages": { "post": { "operationId": "post_v1_messages", "summary": "POST /v1/messages", "description": "Anthropic Messages wire; tools translate both ways — declarations, tool_use/tool_result blocks, tool_choice, streamed tool_use deltas included (server tool types refuse: the router runs no tools)", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" } } } }, "responses": { "200": { "description": "success; with body {\"stream\": true} the same operation answers text/event-stream in this dialect's event framing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "x-iig-balance-microusd": { "description": "the account balance after settlement, micro-USD (buffered responses)", "schema": { "type": "string" } }, "x-iig-class": { "description": "the resolved class when the request rode a class/\u003cname\u003e id", "schema": { "type": "string" } }, "x-iig-cost-microusd": { "description": "what this call cost, micro-USD (buffered responses)", "schema": { "type": "string" } }, "x-iig-generation-id": { "description": "the generation id; resolve billing metadata via GET /v1/generation?id=", "schema": { "type": "string" } }, "x-iig-privacy-tier": { "description": "the retention tier the serving route earned by policy citation", "schema": { "type": "string" } }, "x-iig-provider-hq": { "description": "the serving provider's sourced headquarters country (absent when unknown)", "schema": { "type": "string" } }, "x-iig-usage-type": { "description": "'byok' when the call dispatched on a caller-stored provider key", "schema": { "type": "string" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] }, { "anthropicApiKey": [] } ] } }, "/v1/models": { "get": { "operationId": "get_v1_models", "summary": "GET /v1/models", "description": "catalog + live pricing + class-mode ids", "tags": [ "Catalog" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/models/chooser": { "get": { "operationId": "get_v1_models_chooser", "summary": "GET /v1/models/chooser", "description": "the compact chooser payload (K6): the machine-readable subset a client model picker fetches in one call — same walk as the listing, shape documented in modelsui.go", "tags": [ "Catalog" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChooserList" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth/apps/{clientId}": { "get": { "operationId": "get_v1_oauth_apps_clientId", "summary": "GET /v1/oauth/apps/{clientId}", "description": "public descriptor of one operator-registered OAuth app (D4): the consent screen's app name", "tags": [ "Keys \u0026 auth" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth/authorize": { "post": { "operationId": "post_v1_oauth_authorize", "summary": "POST /v1/oauth/authorize", "description": "consent (session cookie): S256 PKCE challenge + exact registered redirectUri in, single-use short-lived code out, state echoed verbatim", "tags": [ "Keys \u0026 auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ] } }, "/v1/oauth/token": { "post": { "operationId": "post_v1_oauth_token", "summary": "POST /v1/oauth/token", "description": "code + PKCE verifier in, the app's user-scoped INFERENCE-ONLY key out (a D2 row labeled with the app; management routes answer 403; codes burn on any attempt)", "tags": [ "Keys \u0026 auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON body; see the route description" } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "description": "JSON envelope; see the route description" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/responses": { "post": { "operationId": "post_v1_responses", "summary": "POST /v1/responses", "description": "OpenAI Responses wire; tools and structured output refuse 400 (not yet served on this surface — the chat and Messages doors carry tools)", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" } } } }, "responses": { "200": { "description": "success; with body {\"stream\": true} the same operation answers text/event-stream in this dialect's event framing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } }, "headers": { "x-iig-balance-microusd": { "description": "the account balance after settlement, micro-USD (buffered responses)", "schema": { "type": "string" } }, "x-iig-class": { "description": "the resolved class when the request rode a class/\u003cname\u003e id", "schema": { "type": "string" } }, "x-iig-cost-microusd": { "description": "what this call cost, micro-USD (buffered responses)", "schema": { "type": "string" } }, "x-iig-generation-id": { "description": "the generation id; resolve billing metadata via GET /v1/generation?id=", "schema": { "type": "string" } }, "x-iig-privacy-tier": { "description": "the retention tier the serving route earned by policy citation", "schema": { "type": "string" } }, "x-iig-provider-hq": { "description": "the serving provider's sourced headquarters country (absent when unknown)", "schema": { "type": "string" } }, "x-iig-usage-type": { "description": "'byok' when the call dispatched on a caller-stored provider key", "schema": { "type": "string" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } }, "/v1/route-preview": { "get": { "operationId": "get_v1_route_preview", "summary": "GET /v1/route-preview", "description": "routing transparency (A5): ?model=\u003cid|class/\u003cname\u003e|meta alias\u003e answers the resolved candidate ladder AT THIS ACCOUNT's posture and stored preferences — would-serve head, effective prices, privacy tiers, H6 health, a machine-readable reason chain and per-candidate exclusion attribution; read-only (no reserve, no dispatch); ?posture= previews a settings change before saving; the same resolver serving rides, so preview and dispatch cannot disagree", "tags": [ "Catalog" ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePreview" } } } }, "default": { "description": "error, with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] } ] } } }, "components": { "schemas": { "ChatCompletion": { "type": "object", "description": "the OpenAI chat-completion envelope", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "type": "string", "description": "stop | length | tool_calls | content_filter - the upstream's own reason: verbatim from openai-wire providers, mapped from the native adapters (anthropic max_tokens -\u003e length, refusal -\u003e content_filter, tool_use -\u003e tool_calls; gemini MAX_TOKENS -\u003e length, SAFETY/RECITATION/BLOCKLIST/PROHIBITED_CONTENT/SPII/IMAGE_SAFETY -\u003e content_filter). length means the reply was cut at max_tokens (thinking included) - an empty content with length is a budget exhausted, not an answer" }, "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/ChatMessage" } } } }, "id": { "type": "string" }, "model": { "type": "string", "description": "the concrete model that served" }, "object": { "type": "string", "description": "chat.completion" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "id", "object", "choices" ] }, "ChatCompletionsRequest": { "type": "object", "description": "the OpenAI chat-completions body", "properties": { "max_tokens": { "type": "integer", "description": "output-token cap. Absent: the router default 4096 is sent to the native anthropic/gemini adapters (a reasoning model's thinking counts against it) and sizes every call's pre-dispatch reserve; openai-wire upstreams get their provider's own default. Send it explicitly when a reply may run long - finish_reason length / stop_reason max_tokens reports a truncation" }, "messages": { "type": "array", "description": "the conversation (assistant tool_calls and role:tool results included)", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "min_privacy": { "type": "string", "description": "router-local privacy floor: refuse rather than serve below this retention tier" }, "model": { "type": "string", "description": "a catalog id, class/\u003cname\u003e, a meta id (iig/auto, iig/cheap, iig/fast, iig/free, iig/eu), or iig/user-\u003cslug\u003e; :nitro/:floor suffixes re-sort routes" }, "provider": { "type": "object", "description": "router-local provider preferences (stripped before dispatch)" }, "response_format": { "type": "object", "description": "JSON mode ({type: json_object | json_schema}; openai-wire + gemini — refuses param_unsupported on anthropic)" }, "seed": { "type": "integer", "description": "deterministic sampling seed (openai-wire + gemini; refuses param_unsupported on anthropic)" }, "stop": { "oneOf": [ { "type": "string", "description": "one stop sequence" }, { "type": "array", "description": "stop sequences", "items": { "type": "string" } } ] }, "stream": { "type": "boolean", "description": "true answers text/event-stream (SSE), usage in the tail chunk" }, "tags": { "type": "object", "description": "router-local request tags for analytics (stripped before dispatch; also settable via the x-iig-tags header)" }, "temperature": { "type": "number", "description": "sampling temperature" }, "tool_choice": { "oneOf": [ { "type": "string", "description": "auto | none | required" }, { "type": "object", "description": "{type: function, function: {name}}" } ] }, "tools": { "type": "array", "description": "OpenAI function tools — forwarded verbatim to openai-wire providers, translated to the native anthropic/gemini tool shapes", "items": { "type": "object" } }, "top_p": { "type": "number", "description": "nucleus sampling" } }, "required": [ "model", "messages" ] }, "ChatMessage": { "type": "object", "description": "one chat message", "properties": { "content": { "oneOf": [ { "type": "string", "description": "plain text" }, { "type": "array", "description": "content parts (text / image_url)", "items": { "type": "object" } } ] }, "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ] }, "ChooserList": { "type": "object", "description": "the compact chooser payload (shape documented in modelsui.go)", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "one chooser row: id + kind, plus kind-specific fields" } }, "object": { "type": "string", "description": "chooser" } }, "required": [ "object", "data" ] }, "CompliancePacket": { "type": "object", "description": "machine-readable procurement answers, scoped to what is TRUE for this deployment (compliance.go)", "properties": { "audits": { "type": "object", "description": "attested:false — the packet carries no audit or certification claims" }, "contact": { "type": "object", "description": "the configured operator contact, or its honest absence" }, "deployment": { "type": "object", "description": "this deployment's identity", "properties": { "mode": { "type": "string", "enum": [ "local", "backend" ] }, "serverId": { "type": "string" }, "service": { "type": "string", "description": "iig" } } }, "note": { "type": "string", "description": "the honesty contract: derived live or pointing at the endpoint that proves it; 'not configured' / 'not attested' over invented values" }, "object": { "type": "string", "description": "compliance" }, "retention": { "type": "object", "description": "what this router stores (transcripts: none) and the cited upstream tier ladder with live per-tier route counts" }, "security": { "type": "object", "description": "pointers onto the security page and the trust surface" }, "status": { "type": "object", "description": "pointers onto the split-SLO status surface" }, "subprocessors": { "type": "object", "description": "the upstream providers request content can actually reach on the shared prepaid lane", "properties": { "builtin": { "type": "string", "description": "why the in-process 'iig' provider is not a subprocessor" }, "data": { "type": "array", "description": "one row per configured provider, sorted by slug", "items": { "type": "object", "properties": { "hq": { "type": "object", "description": "sourced headquarters claim (F3); absent when unknown" }, "models": { "type": "integer", "description": "served catalog routes dispatching to this provider right now" }, "name": { "type": "string", "description": "display name" }, "privacy": { "type": "object", "description": "the provider-wide retention posture (F1), citation riding non-standard tiers" }, "provider": { "type": "string", "description": "the slug" } }, "required": [ "provider", "models", "privacy" ] } }, "note": { "type": "string", "description": "the derivation rule: an operator-pooled key AND at least one served catalog route" }, "otherLanes": { "type": "string", "description": "tenant-dedicated and BYOK keys are per-account lanes, described not enumerated" } }, "required": [ "note", "data" ] } }, "required": [ "object", "subprocessors", "retention", "status", "contact" ] }, "CoverageMap": { "type": "object", "description": "the honest wire map GET /coverage serves", "properties": { "object": { "type": "string", "description": "coverage" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "real", "stub" ] }, "method": { "type": "string", "description": "HTTP method, or * for a whole route family" }, "note": { "type": "string" }, "path": { "type": "string" } }, "required": [ "method", "path", "kind" ] } }, "service": { "type": "string", "description": "iig" } }, "required": [ "object", "routes" ] }, "EmbeddingList": { "type": "object", "description": "the embeddings envelope", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "embedding": { "type": "array", "description": "the vector", "items": { "type": "number" } }, "index": { "type": "integer" }, "object": { "type": "string", "description": "embedding" } } } }, "iig_upstream": { "type": "object", "description": "upstream attribution (IIG extension): what actually served the batch", "properties": { "adapter": { "type": "string", "enum": [ "echo", "openai-wire", "native" ] }, "dimensions": { "type": "integer", "description": "output dimension of the returned vectors" }, "input_type": { "type": "string", "description": "the asymmetric hint actually forwarded (omitted when none was)" }, "model": { "type": "string", "description": "upstream model id actually used ('echo' self-identifies)" }, "provider": { "type": "string", "description": "resolved serving provider ('iig' = the local echo rung)" } } }, "model": { "type": "string", "description": "the resolved catalog model id" }, "object": { "type": "string", "description": "list" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } }, "required": [ "object", "data" ] }, "EmbeddingsRequest": { "type": "object", "description": "the embeddings body (input tokens only are billed)", "properties": { "dimensions": { "type": "integer", "description": "optional MRL output-dimension knob (1..8192; forwarded under each provider's own field name)" }, "input": { "oneOf": [ { "type": "string", "description": "one text" }, { "type": "array", "description": "up to 16 texts", "items": { "type": "string" } } ] }, "input_type": { "type": "string", "description": "optional asymmetric-retrieval hint: 'query' or 'document' (forwarded to voyage-family models, ignored elsewhere)" }, "model": { "type": "string", "description": "an embeddings-capable catalog id" } }, "required": [ "model", "input" ] }, "Error": { "type": "object", "description": "the stable error envelope every JSON door answers — inference, embeddings, and management routes alike. The Messages door (/v1/messages) keeps the Anthropic nesting ({type:\"error\", error:{...}}) with its inner type projected from the SAME closed vocabulary; code and any detail fields ride beside it identically. Streaming failures AFTER the 200 headers emit one documented SSE error event in the door's framing (chat completions: a data chunk carrying this envelope; /v1/responses: an `error` event; /v1/messages: the Anthropic `error` event) as the stream's last meaningful frame — a clean [DONE]/terminal only ever closes a clean upstream end; the call settles from the text received so far, marked estimated.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (e.g. unauthorized, bad_request, not_supported, insufficient_credits — the account balance; key_cap_exceeded / spend_window_exceeded — a per-key bound, the error names WHICH key; a 401 for a key whose MATERIAL is recognized names its state — key_disabled, key_expired, key_exhausted (a browser key's use budget), key_revoked (deleted/rotated away) — and the message names the key's masked hint, while a truly unknown key stays the uniform unauthorized; param_unsupported names a sampling/tool parameter the serving provider's wire cannot express — refused honestly, never dropped; traffic protection adds rate_limited — a 429 carrying Retry-After in whole seconds, per API key, account, or unauthenticated address — server_busy — a 503 shed at the router's concurrent-request capacity, also with Retry-After — persistence_unavailable — a 503 + Retry-After while the billing durability layer recovers; nothing was dispatched or held — and holds_exceeded — a 429 refusing a new reservation while the account already sits at its open-holds bound; wait for in-flight calls to settle)" }, "message": { "type": "string", "description": "human-readable detail" }, "type": { "type": "string", "description": "the CLOSED error-type vocabulary — the field to switch on. Retryability is part of the contract: rate_limited and unavailable are retryable after the Retry-After header's seconds (transient store contention and capacity sheds always stamp it); upstream_error MAY be retried (a different model or moment can succeed); everything else is deterministic — fix the request, credential, or account first. insufficient_credits means the ACCOUNT cannot pay (the error carries topUpUrl plus availableMicroUsd/neededMicroUsd); spend_cap_exceeded means a per-key cap or spend window binds while the balance is untouched (the error names the binding key: key.hash/hint/label)", "enum": [ "invalid_request", "authentication", "insufficient_credits", "spend_cap_exceeded", "permission", "not_found", "conflict", "rate_limited", "internal", "not_supported", "upstream_error", "unavailable" ] } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] }, "Message": { "type": "object", "description": "the Anthropic Messages envelope", "properties": { "content": { "type": "array", "description": "content blocks (text / tool_use)", "items": { "type": "object" } }, "id": { "type": "string" }, "role": { "type": "string", "description": "assistant" }, "stop_reason": { "type": "string", "description": "end_turn | max_tokens | refusal | tool_use - the upstream's own reason (an anthropic max_tokens truncation echoes max_tokens; openai-wire length maps to max_tokens, content_filter to refusal)" }, "type": { "type": "string", "description": "message" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } } }, "required": [ "id", "type", "role", "content" ] }, "MessagesRequest": { "type": "object", "description": "the Anthropic Messages body", "properties": { "max_tokens": { "type": "integer", "description": "required by the Anthropic dialect" }, "messages": { "type": "array", "description": "user/assistant turns; content as text or typed blocks (text / image / document / tool_use / tool_result)", "items": { "type": "object" } }, "model": { "type": "string", "description": "same id space as chat completions" }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean", "description": "true answers the Messages event stream" }, "system": { "oneOf": [ { "type": "string", "description": "system prompt" }, { "type": "array", "description": "system blocks", "items": { "type": "object" } } ] }, "temperature": { "type": "number" }, "tool_choice": { "type": "object", "description": "{type: auto | any | tool | none, name?, disable_parallel_tool_use?}" }, "tools": { "type": "array", "description": "client tool declarations ({name, description?, input_schema?}) — translated to the canonical function-tool lane; server tool types refuse (the router runs no tools)", "items": { "type": "object" } }, "top_p": { "type": "number" } }, "required": [ "model", "messages", "max_tokens" ] }, "ModelList": { "type": "object", "description": "the catalog listing (prices, privacy citations, jurisdiction)", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "one catalog row; see the route description" } }, "object": { "type": "string", "description": "list" } }, "required": [ "object", "data" ] }, "Response": { "type": "object", "description": "the OpenAI Responses envelope", "properties": { "id": { "type": "string" }, "object": { "type": "string", "description": "response" }, "output": { "type": "array", "description": "output items (message with output_text parts)", "items": { "type": "object" } }, "status": { "type": "string", "description": "completed" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } }, "required": [ "id", "object", "output" ] }, "ResponsesRequest": { "type": "object", "description": "the OpenAI Responses body", "properties": { "input": { "oneOf": [ { "type": "string", "description": "plain text" }, { "type": "array", "description": "input items", "items": { "type": "object" } } ] }, "instructions": { "type": "string", "description": "system prompt" }, "max_output_tokens": { "type": "integer" }, "model": { "type": "string", "description": "same id space as chat completions" }, "stream": { "type": "boolean", "description": "true answers the response.* event stream" }, "temperature": { "type": "number" } }, "required": [ "model", "input" ] }, "RoutePreview": { "type": "object", "description": "the resolved routing preview (A5): the candidate ladder at this account's posture and preferences, would-serve head, and the machine-readable reason chain — read-only, the same resolver serving rides", "properties": { "candidates": { "type": "array", "description": "the final try order: position (the H5 rollover position; 0 serves), model, provider, effective pricing pair, resolved privacyTier, healthy (H6), servesNow", "items": { "type": "object" } }, "class": { "type": "string", "description": "the class name (class kind only)" }, "excluded": { "type": "array", "description": "candidates the resolution excluded, each with the FIRST failing filter named: not_in_catalog, retired, no_provider_key, privacy_floor, jurisdiction, provider_excluded, rollover_limit, no_fallbacks", "items": { "type": "object" } }, "kind": { "type": "string", "enum": [ "class", "meta", "model" ] }, "object": { "type": "string", "description": "route_preview" }, "posture": { "type": "string", "enum": [ "quality", "balanced", "low-cost" ] }, "postureSource": { "type": "string", "description": "'preview' when ?posture= overrode the account's stored posture for this answer only", "enum": [ "account", "preview" ] }, "reasons": { "type": "array", "description": "the machine-readable reason chain: {code, detail} — codes posture, meta_order, privacy_floor, jurisdiction, preference_only/ignore/order, sort, no_fallbacks, health, echo_backstop, rollover", "items": { "type": "object" } }, "refusal": { "type": "object", "description": "when the serving door would refuse this id outright: {code, message} (same codes as dispatch); absent when a candidate serves" }, "requested": { "type": "string", "description": "the id as asked (suffix included)" }, "wouldServe": { "type": "object", "description": "the candidate that would serve NOW (candidates[0]); null when nothing serves — see refusal + excluded" } }, "required": [ "object", "requested", "kind", "posture", "candidates", "reasons" ] }, "Usage": { "type": "object", "description": "token usage as billed", "properties": { "completion_tokens": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "required": [ "prompt_tokens", "total_tokens" ] } }, "securitySchemes": { "anthropicApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "the Anthropic SDK header; accepted by POST /v1/messages alongside bearer" }, "bearerKey": { "type": "http", "scheme": "bearer", "description": "an account API key (minted in the console or via POST /v1/keys)" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "iig_session", "description": "the identity-hook session (POST /v1/auth/signin)" } } } }