{ "openapi": "3.1.0", "info": { "title": "Darouter HTTP API", "version": "1.1.0-preview", "description": "Exact-current public drop-in surface. Unknown or unpreserved request fields are HTTP 400, not silently dropped. This is not a GA compatibility commitment. Responses retrieve is GET /v1/responses/{id} for store:true. Conversation state is not implemented. POST /v1/messages/count_tokens and Gemini :countTokens return a local ~4-character-per-token estimate (not a billed provider tokenizer). Breaking-change policy: preview paths may change; deprecation requires a FEATURE-MATRIX note and a sunset header before removal. See docs/API-COMPATIBILITY.md." }, "servers": [ { "url": "https://api.cybertronic.dev", "description": "Canonical public hostname" } ], "tags": [ { "name": "drop-in" }, { "name": "discovery" }, { "name": "identity" }, { "name": "optimizer" }, { "name": "evaluation" }, { "name": "portal-security" } ], "paths": { "/v1/openapi.json": { "get": { "tags": ["discovery"], "operationId": "getOpenAPI", "summary": "This OpenAPI document", "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/signup": { "post": { "tags": ["identity"], "operationId": "createSignup", "summary": "Create a starter project and send contact email verification", "description": "Opt-in public signup. Requires a normalized contact email, binds it to the minted organization/project, and sends a single-use expiring verification token. The token is never returned by this response. Returns 404 when public signup is disabled.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } } }, "responses": { "201": { "description": "Starter project created and verification message accepted for delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Public signup is disabled" }, "429": { "description": "Process-local signup rate limit exceeded" }, "503": { "description": "Signup, contact email storage, or verification delivery is unavailable" } } } }, "/v1/contact-email/verify": { "post": { "tags": ["identity"], "operationId": "verifyContactEmail", "summary": "Consume a contact email verification token", "description": "Consumes one single-use expiring token. Invalid, expired, and replayed tokens fail closed with the same response and token material is never echoed.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEmailVerifyRequest" } } } }, "responses": { "200": { "description": "Contact email verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEmailVerificationResponse" } } } }, "400": { "description": "Invalid, expired, or replayed verification token" }, "503": { "description": "Contact email verification is unavailable" } } } }, "/v1/contact-email/resend": { "post": { "tags": ["identity"], "operationId": "resendContactEmailVerification", "summary": "Request another contact email verification message", "description": "Always returns the same generic 202 response for pending, verified, invalid, and unknown email addresses. Only a known pending contact receives a replacement token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEmailResendRequest" } } } }, "responses": { "202": { "description": "Generic non-enumerating acceptance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEmailResendResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/models": { "get": { "tags": ["discovery"], "operationId": "listModels", "summary": "List executable models", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OpenAI-shaped model list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/models/{id}": { "get": { "tags": ["discovery"], "operationId": "retrieveModel", "summary": "Retrieve one executable model", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OpenAI-shaped model object from the same list as GET /v1/models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown, hidden, or sunset model" } } } }, "/v1/chat/completions": { "post": { "tags": ["drop-in"], "operationId": "createChatCompletion", "summary": "OpenAI-shaped chat completions", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "X-Darouter-Task-Type", "in": "header", "required": false, "description": "Content-free optimizer task class. Defaults to general_chat. A task-specific policy takes precedence; otherwise the existing general_chat policy remains in control.", "schema": { "type": "string", "enum": ["general_chat", "game_creation", "game_repair", "game_refinement"] } }, { "name": "X-Darouter-Session-ID", "in": "header", "required": false, "description": "Stable non-secret ID for one tool session. Hashed before storage; pins an optimizer policy arm only when session affinity is enabled for that policy.", "schema": { "type": "string" } }, { "name": "X-Darouter-Profile-Chain", "in": "header", "required": false, "description": "Opt-in native-history continuity. start or continue requires the same non-secret session ID plus the exact profile version and execution target IDs returned by GET /v1/model-profiles/{alias}. Incompatible changes return 409 before provider dispatch; no cross-model fallback is attempted.", "schema": { "type": "string", "enum": ["start", "continue"] } }, { "name": "X-Darouter-Profile-Version-ID", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "X-Darouter-Execution-Target-ID", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "X-Darouter-Profile-Session-Token", "in": "header", "required": false, "description": "Opaque server HMAC receipt returned by start; required on continue with the same authenticated key, session and profile IDs. Issued before dispatch and may accompany a later provider or budget error.", "schema": { "type": "string", "minLength": 43, "maxLength": 43 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } }, "responses": { "200": { "description": "Chat completion or SSE when stream=true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Native-history profile receipt is incompatible; no provider dispatch" } } } }, "/v1/model-profiles/{alias}": { "get": { "tags": ["governance"], "operationId": "getModelProfileContract", "summary": "Read the caller's active single-target native-history profile", "description": "Project-key scoped; returns content-free alias/version/target identity and configured model capability limits. capabilities.vision and input_contract.modalities explicitly distinguish image input from tools or image generation. input_contract.images is null for text-only targets; otherwise it exposes existing parser limits (8 images, 524288 bytes per inline data URL, 1048576 bytes total request body), supported media/detail values and remote_urls_allowed=false. Pixel dimensions and image pricing qualification remain unavailable, not implied by parser support. These are configured serving capabilities, not a successful screenshot-review qualification or a guarantee of provider image billing. Unknown limits and unverified reasoning levels are null. Multi-target aliases return 409 until a safe continuity envelope is defined.", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "alias", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Active profile and configured capability envelope", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown or foreign-project profile" }, "409": { "description": "Profile has multiple active targets; native continuity is not supported" }, "503": { "description": "Target is unavailable or not executable" } } } }, "/v1/inference-budget": { "get": { "tags": ["budgets"], "operationId": "getOwnInferenceBudget", "summary": "Read only the authenticating project's own key ledger", "description": "Returns key hard limit, booked spend, and an upper-bound remaining amount before in-flight reservations. The launch gate, not this read, authoritatively enforces spending. No secret or sibling-key data is returned.", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "profile", "in": "query", "required": false, "description": "Optional authorized profile alias; includes matching atomic reservation pools for its concrete target. Key metadata alone is not proof of pre-dispatch reservation enforcement.", "schema": { "type": "string" } }], "responses": { "200": { "description": "Own key ledger", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Key not found in authenticated project" }, "503": { "description": "Key ledger is unavailable" } } } }, "/v1/embeddings": { "post": { "tags": ["drop-in"], "operationId": "createEmbedding", "summary": "OpenAI-shaped embeddings", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" } } } }, "responses": { "200": { "description": "Embedding response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/videos": { "post": { "tags": ["drop-in"], "operationId": "createVideo", "summary": "Video generation capability status (#948)", "description": "Video generation is not provider-backed on this deployment. This authenticated endpoint returns 501 without creating a job, contacting a provider, or recording a billable attempt.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "Video generation is not enabled in this deployment" } } } }, "/v1/videos/{video_id}": { "get": { "tags": ["drop-in"], "operationId": "getVideo", "summary": "Video generation capability status (#948)", "description": "Video jobs are not provider-backed on this deployment. This authenticated endpoint returns 501 without creating, polling, or mutating a job.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "Video generation is not enabled in this deployment" } } } }, "/v1/videos/{video_id}/cancel": { "post": { "tags": ["drop-in"], "operationId": "cancelVideo", "summary": "Video generation capability status (#948)", "description": "Video jobs are not provider-backed on this deployment. This authenticated endpoint returns 501 without creating, polling, or mutating a job.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "Video generation is not enabled in this deployment" } } } }, "/v1/images/generations": { "post": { "tags": ["drop-in"], "operationId": "createImageGeneration", "summary": "OpenAI-shaped image generation (#841 images slice)", "description": "Capability-gated generic passthrough: authenticates, rate limits, routes/falls back, circuit-breaks, and bills via a model's listed PerCallCost (no token usage is parsed), then forwards the request/response bytes unchanged to a model advertising images. Returns 501 when no eligible model advertises the capability, instead of the generic 400 other passthrough endpoints return on a capability miss.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" } } } }, "responses": { "200": { "description": "OpenAI-shaped image generation result, forwarded byte-for-byte from the upstream provider", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "No eligible model advertises the images capability in this deployment" } } } }, "/v1/images/edits": { "post": { "tags": ["drop-in"], "operationId": "createImageEdit", "summary": "OpenAI-shaped image edit (#841 images slice)", "description": "Capability-gated generic passthrough for POST /images/edits. Accepts application/json or multipart/form-data (the upstream OpenAI shape). Returns 501 when no eligible model advertises the images capability.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" } }, "multipart/form-data": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OpenAI-shaped image edit result, forwarded byte-for-byte from the upstream provider", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "No eligible model advertises the images capability in this deployment" } } } }, "/v1/moderations": { "post": { "tags": ["drop-in"], "operationId": "createModeration", "summary": "OpenAI-shaped content moderation (#841 first slice)", "description": "Capability-gated generic passthrough: authenticates, rate limits, routes/falls back, circuit-breaks, and bills via a model's listed PerCallCost (no token usage is parsed), then forwards the request/response bytes unchanged to a model advertising moderation. Returns 501 when no eligible model advertises the capability, instead of the generic 400 other passthrough endpoints return on a capability miss.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModerationRequest" } } } }, "responses": { "200": { "description": "OpenAI-shaped moderation result, forwarded byte-for-byte from the upstream provider", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "No eligible model advertises the moderation capability in this deployment" } } } }, "/v1/audio/speech": { "post": { "tags": ["drop-in"], "operationId": "createSpeech", "summary": "OpenAI-shaped speech synthesis (#948 modalities slice)", "description": "Capability-gated generic passthrough for POST /audio/speech. Returns binary audio or JSON metadata from the upstream provider. Returns 501 when no eligible model advertises the audio-speech capability.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechRequest" } } } }, "responses": { "200": { "description": "OpenAI-shaped speech synthesis result (typically audio/mpeg), forwarded from the upstream provider", "content": { "application/json": { "schema": { "type": "object" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "No eligible model advertises the audio-speech capability in this deployment" } } } }, "/v1/audio/transcriptions": { "post": { "tags": ["drop-in"], "operationId": "createTranscription", "summary": "OpenAI-shaped audio transcription (#948 modalities slice)", "description": "Capability-gated generic passthrough for POST /audio/transcriptions. Accepts multipart/form-data (the upstream OpenAI shape). Returns 501 when no eligible model advertises the audio-transcription capability.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OpenAI-shaped transcription result, forwarded byte-for-byte from the upstream provider", "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "No eligible model advertises the audio-transcription capability in this deployment" } } } }, "/v1/rerank": { "post": { "tags": ["drop-in"], "operationId": "createRerank", "summary": "OpenAI-compatible rerank (#948 modalities slice)", "description": "Capability-gated generic passthrough for POST /rerank (Cohere/Jina-shaped via OpenAI-compatible gateways). Returns 501 when no eligible model advertises the rerank capability.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" } } } }, "responses": { "200": { "description": "Rerank result, forwarded byte-for-byte from the upstream provider", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "No eligible model advertises the rerank capability in this deployment" } } } }, "/v1/files": { "post": { "tags": ["drop-in"], "operationId": "createFile", "summary": "Upload a purpose=batch or purpose=fine-tune JSONL file", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OpenAI-shaped file object" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": ["drop-in"], "operationId": "listFiles", "summary": "List this tenant's uploaded files", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OpenAI-shaped file list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/files/{id}": { "get": { "tags": ["drop-in"], "operationId": "getFile", "summary": "Retrieve file metadata", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OpenAI-shaped file object" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found" } } }, "delete": { "tags": ["drop-in"], "operationId": "deleteFile", "summary": "Delete a file", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted file object" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found" } } } }, "/v1/files/{id}/content": { "get": { "tags": ["drop-in"], "operationId": "getFileContent", "summary": "Download file bytes", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw JSONL bytes" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found" } } } }, "/v1/batches": { "post": { "tags": ["drop-in"], "operationId": "createBatch", "summary": "Create a chat batch from a purpose=batch file", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OpenAI-shaped batch object" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": ["drop-in"], "operationId": "listBatches", "summary": "List this tenant's batches", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OpenAI-shaped batch list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/batches/{id}": { "get": { "tags": ["drop-in"], "operationId": "getBatch", "summary": "Retrieve a batch", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OpenAI-shaped batch object" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found" } } } }, "/v1/batches/{id}/cancel": { "post": { "tags": ["drop-in"], "operationId": "cancelBatch", "summary": "Cancel an in-flight batch", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OpenAI-shaped batch object" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found" } } } }, "/v1/fine_tuning/jobs": { "post": { "tags": ["drop-in"], "operationId": "createFineTuningJob", "summary": "Create a fine-tuning job from a purpose=fine-tune file", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OpenAI-shaped fine-tuning job" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": ["drop-in"], "operationId": "listFineTuningJobs", "summary": "List this tenant's fine-tuning jobs", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OpenAI-shaped fine-tuning job list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/fine_tuning/jobs/{id}": { "get": { "tags": ["drop-in"], "operationId": "getFineTuningJob", "summary": "Retrieve a fine-tuning job", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OpenAI-shaped fine-tuning job" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found" } } } }, "/v1/fine_tuning/jobs/{id}/cancel": { "post": { "tags": ["drop-in"], "operationId": "cancelFineTuningJob", "summary": "Cancel a fine-tuning job", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OpenAI-shaped fine-tuning job" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found" }, "409": { "description": "Job already terminal" } } } }, "/v1/messages": { "post": { "tags": ["drop-in"], "operationId": "createMessage", "summary": "Native Anthropic Messages", "security": [{ "bearerAuth": [] }, { "xApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Anthropic message or SSE", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/messages/count_tokens": { "post": { "tags": ["drop-in"], "operationId": "countMessageTokens", "summary": "Local Anthropic Messages token estimate", "description": "Returns {input_tokens} from EstimateChatRequestTokens (~4 characters per token). Does not dispatch, charge, or call a billed provider. Not Anthropic tokenizer exactness. Unknown fields are 400. stream=true is 400. max_tokens is optional.", "security": [{ "bearerAuth": [] }, { "xApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Local input token estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0 } }, "required": ["input_tokens"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/responses": { "post": { "tags": ["drop-in"], "operationId": "createResponse", "summary": "OpenAI Responses", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Response object or SSE", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/responses/{id}": { "get": { "tags": ["drop-in"], "operationId": "retrieveResponse", "summary": "Retrieve a stored Response", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OpenAI-shaped Response object" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found" } } } }, "/v1beta/models/{model}:generateContent": { "post": { "tags": ["drop-in"], "operationId": "generateContentV1beta", "summary": "Native Gemini generateContent", "security": [{ "bearerAuth": [] }, { "xGoogApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Gemini generateContent response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/models/{model}:generateContent": { "post": { "tags": ["drop-in"], "operationId": "generateContentV1", "summary": "Native Gemini generateContent (v1 alias)", "security": [{ "bearerAuth": [] }, { "xGoogApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Gemini generateContent response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1beta/models/{model}:streamGenerateContent": { "post": { "tags": ["drop-in"], "operationId": "streamGenerateContentV1beta", "summary": "Native Gemini streamGenerateContent SSE", "security": [{ "bearerAuth": [] }, { "xGoogApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Gemini streamGenerateContent SSE (text/event-stream)", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/models/{model}:streamGenerateContent": { "post": { "tags": ["drop-in"], "operationId": "streamGenerateContentV1", "summary": "Native Gemini streamGenerateContent SSE (v1 alias)", "security": [{ "bearerAuth": [] }, { "xGoogApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Gemini streamGenerateContent SSE (text/event-stream)", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1beta/models/{model}:countTokens": { "post": { "tags": ["drop-in"], "operationId": "countTokensV1beta", "summary": "Local Gemini countTokens estimate", "description": "Returns {totalTokens} from EstimateChatRequestTokens (~4 characters per token). Does not dispatch, charge, or call a billed provider. Not Gemini tokenizer exactness. Unknown fields are 400. Query ?key= is 400.", "security": [{ "bearerAuth": [] }, { "xGoogApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Local totalTokens estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalTokens": { "type": "integer", "minimum": 0 } }, "required": ["totalTokens"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/models/{model}:countTokens": { "post": { "tags": ["drop-in"], "operationId": "countTokensV1", "summary": "Local Gemini countTokens estimate (v1 alias)", "description": "Same local estimate as /v1beta/models/{model}:countTokens.", "security": [{ "bearerAuth": [] }, { "xGoogApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Local totalTokens estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalTokens": { "type": "integer", "minimum": 0 } }, "required": ["totalTokens"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/evaluation/datasets": { "post": { "tags": ["evaluation"], "operationId": "createEvaluationDatasetVersion", "summary": "Create an immutable tenant-owned evaluation dataset version", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDatasetVersionInput" } } } }, "responses": { "201": { "description": "Created dataset version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDatasetVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "That version already exists" } } } }, "/v1/evaluation/datasets/{dataset_id}/versions": { "get": { "tags": ["evaluation"], "operationId": "listEvaluationDatasetVersions", "summary": "List dataset versions owned by the authenticated project", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Dataset versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDatasetVersionList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/evaluation/evaluators": { "post": { "tags": ["evaluation"], "operationId": "createEvaluationEvaluatorVersion", "summary": "Create an immutable tenant-owned evaluator version", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationEvaluatorVersionInput" } } } }, "responses": { "201": { "description": "Created evaluator version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationEvaluatorVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "That version already exists" } } } }, "/v1/evaluation/evaluators/{evaluator_id}/versions": { "get": { "tags": ["evaluation"], "operationId": "listEvaluationEvaluatorVersions", "summary": "List evaluator versions owned by the authenticated project", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "evaluator_id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Evaluator versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationEvaluatorVersionList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/evaluation/experiments": { "post": { "tags": ["evaluation"], "operationId": "createEvaluationExperiment", "summary": "Create an offline or shadow experiment for governance-eligible policy versions", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationExperimentInput" } } } }, "responses": { "201": { "description": "Created experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationExperiment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Policy or versions are not governance eligible" } } }, "get": { "tags": ["evaluation"], "operationId": "listEvaluationExperiments", "summary": "List experiments owned by the authenticated project", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Experiments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationExperimentList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/evaluation/experiments/{experiment_id}": { "get": { "tags": ["evaluation"], "operationId": "getEvaluationExperiment", "summary": "Get one tenant-owned experiment", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationExperiment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/evaluation/experiments/{experiment_id}/evidence": { "post": { "tags": ["evaluation"], "operationId": "recordEvaluationEvidence", "summary": "Record separate quality, cost, latency, reliability, sample, and uncertainty evidence", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationEvidence" } } } }, "responses": { "200": { "description": "Updated experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationExperiment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/evaluation/experiments/{experiment_id}/feedback": { "post": { "tags": ["evaluation"], "operationId": "recordEvaluationFeedback", "summary": "Record application feedback bound to an exact decision and attempt", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationFeedbackBinding" } } } }, "responses": { "200": { "description": "Updated experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationExperiment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Duplicate feedback or terminal experiment" } } } }, "/v1/evaluation/experiments/{experiment_id}/promote": { "post": { "tags": ["evaluation"], "operationId": "promoteEvaluationExperiment", "summary": "Promote only with configured floors and sufficient statistical evidence", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDecisionInput" } } } }, "responses": { "200": { "description": "Promoted experiment" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Experiment already terminal" }, "422": { "description": "Evidence does not satisfy the configured gate" } } } }, "/v1/evaluation/experiments/{experiment_id}/rollback": { "post": { "tags": ["evaluation"], "operationId": "rollbackEvaluationExperiment", "summary": "Rollback only on fresh regression evidence", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDecisionInput" } } } }, "responses": { "200": { "description": "Rolled-back experiment" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Experiment already terminal" }, "422": { "description": "Fresh regression evidence is insufficient" } } } }, "/portal/mfa/enroll": { "post": { "tags": ["portal-security"], "operationId": "enrollPortalMFA", "summary": "Enroll an authenticator factor for the current SSO portal subject", "security": [{ "portalSession": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["label"], "additionalProperties": false, "properties": { "label": { "type": "string", "maxLength": 128 } } } } } }, "responses": { "201": { "description": "One-time setup material and public factor metadata" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "An API-key portal session cannot enroll MFA" } } } }, "/portal/mfa/factors": { "get": { "tags": ["portal-security"], "operationId": "listPortalMFAFactors", "summary": "List current subject MFA factor metadata", "security": [{ "portalSession": [] }], "responses": { "200": { "description": "Factor metadata; no secrets or recovery codes" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/portal/mfa/challenge": { "post": { "tags": ["portal-security"], "operationId": "challengePortalMFA", "summary": "Verify a TOTP code and mark the current session MFA-verified", "security": [{ "portalSession": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalMFACode" } } } }, "responses": { "200": { "description": "MFA verified" }, "401": { "description": "Generic invalid/unknown/foreign code failure" }, "429": { "description": "Temporary lockout" } } } }, "/portal/mfa/recovery": { "post": { "tags": ["portal-security"], "operationId": "recoverPortalMFA", "summary": "Consume one recovery code for the current SSO portal subject", "security": [{ "portalSession": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalMFACode" } } } }, "responses": { "200": { "description": "MFA recovered" }, "401": { "description": "Generic invalid/unknown/foreign/consumed code failure" } } } }, "/portal/mfa/revoke": { "post": { "tags": ["portal-security"], "operationId": "revokePortalMFA", "summary": "Revoke a factor for the current SSO portal subject", "security": [{ "portalSession": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["factor_id"], "additionalProperties": false, "properties": { "factor_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Factor revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/portal/mfa/policy": { "post": { "tags": ["portal-security"], "operationId": "setPortalMFAPolicy", "summary": "Set whether this organization requires MFA for portal human-admin mutations", "security": [{ "portalSession": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["required"], "additionalProperties": false, "properties": { "required": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated organization MFA policy" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Owner permission or SSO session required" } } } }, "/v1/optimizer/outcomes": { "post": { "tags": ["optimizer"], "operationId": "reportOptimizerOutcome", "summary": "Report an application/user outcome for an optimizer decision", "description": "Tenant-scoped, idempotent on (decision_id, idempotency_key); reporting a duplicate idempotency_key with the same payload replays accepted=true,duplicate=true, a conflicting payload is 409. Scoped to the caller's own project: an unknown or another tenant's decision_id is 404, never distinguishable from a truly unknown id. user_feedback/task_metrics accept only a fixed allowlist of content-free scalars (task_metrics: latency_ms/tokens/cost_usd/ttft_ms numbers, cache_hit/tool_call_valid and game-stage booleans, error_class string; user_feedback: rating number, thumbs_up boolean, comment_hash string) -- unknown keys, nested values, and prompt/response/message/credential-shaped keys or values are rejected with 400 before anything is persisted. Known Verse source-validator and build outcomes are accepted as audit-only milestones and never train task success; a positive game-stage report trains only when browser play, novelty and polish pass. This endpoint never stores or returns raw prompt/completion bodies. Tenant API keys may only claim source=application/user/rule/judge_model/synthetic/test; source=human or source=verifier is 403 here and requires the admin-token-gated POST /admin/optimizer/outcomes. Public Tunnel/Worker allowlist this path.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizerOutcomeRequest" } } } }, "responses": { "200": { "description": "Outcome accepted, either freshly recorded or a recognized idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizerOutcomeResponse" } } } }, "400": { "description": "Invalid payload shape, missing decision_id/idempotency_key, unknown source, or outcome metadata failed the content-free allowlist" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "source=human or source=verifier requires POST /admin/optimizer/outcomes" }, "404": { "description": "Unknown decision_id, or the decision belongs to another tenant" }, "409": { "description": "idempotency_key already used with a different source or success value" } } } }, "/v1/operations/usage/exports": { "post": { "tags": ["usage"], "operationId": "createTenantUsageExport", "summary": "Create an asynchronous tenant usage export", "description": "Pins a bounded UTC [from,to) window and durable billable-event snapshot time. The job is organization/project scoped, expires after 24 hours, and never includes prompts, responses, credentials, or API keys.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "enum": ["day", "hour"], "default": "day" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["json", "csv"], "default": "json" } } ], "responses": { "202": { "description": "Queued export job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageExportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Requested foreign scope is not disclosed" }, "503": { "description": "Usage export or audit storage unavailable" } } } }, "/v1/operations/usage/exports/{id}": { "get": { "tags": ["usage"], "operationId": "getTenantUsageExport", "summary": "Get asynchronous tenant usage export status", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageExportJob" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown or foreign export job" } } } }, "/v1/operations/usage/exports/{id}/download": { "get": { "tags": ["usage"], "operationId": "downloadTenantUsageExport", "summary": "Download a completed tenant usage export", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV or JSON export bytes" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown or foreign export job" }, "409": { "description": "Export is not complete" }, "410": { "description": "Export expired" } } } }, "/v1/operations/usage/series": { "get": { "tags": ["usage"], "operationId": "getTenantUsageSeries", "summary": "Retrieve bounded tenant usage time series", "description": "Returns request volume, provider-attempt mix, and rated spend from the durable provider_billable_events source for the authenticated tenant. bucket=day (default) or hour; default window is 30 days, with maximum windows of 366 days for day buckets and 31 days for hour buckets. Empty windows return an empty series. Latency is explicitly null/unavailable because it is not recorded in the billable-event contract; HTTP 200 is never quality.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Inclusive window start (RFC3339 or YYYY-MM-DD)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exclusive window end (RFC3339 or YYYY-MM-DD; date-only is next-day exclusive)" }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "enum": ["day", "hour"] } }, { "name": "organization_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional assertion; must match the authenticated organization" }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional assertion; must match the authenticated project" } ], "responses": { "200": { "description": "Bounded tenant usage series, possibly empty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUsageSeries" } } } }, "400": { "description": "Invalid window or bucket" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Organization or project assertion does not belong to the authenticated tenant" }, "501": { "description": "Durable usage time-series store is not configured" }, "503": { "description": "Durable billable event store is temporarily unavailable" } } } }, "/v1/optimizer/aggregates": { "get": { "tags": ["optimizer"], "operationId": "listOptimizerAggregates", "summary": "Tenant-scoped routing/reliability aggregates over an evidence window", "description": "Returns cost, latency, TTFT, error, hedge/fallback, and cache rollups reconciled to optimizer decisions/attempts for the caller's project. winner_cost_micros sums won attempts only (no double-counting primary+fallback/hedge). decisions_missing_outcome counts censored/absent outcomes — never quality=0. Optional from/to use the same RFC3339 or YYYY-MM-DD window semantics as GET /v1/operations/usage. bucket=day|hour adds bounded time-series buckets. format=csv returns a flat bounded export.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Inclusive window start (RFC3339 or YYYY-MM-DD)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exclusive window end (RFC3339 or YYYY-MM-DD; date-only is next-day exclusive)" }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "enum": ["day", "hour"] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["json", "csv"] } } ], "responses": { "200": { "description": "Aggregates for the evidence window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizerRoutingAggregates" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid from/to window" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "Optimizer control plane is not configured" } } } }, "/v1/benchmarks": { "get": { "tags": ["benchmarks"], "operationId": "listTenantBenchmarkScores", "summary": "List published benchmark scorecards for the tenant project", "description": "Returns read-only scorecards computed from the caller's active serving policies. Draft policies, experiments, and sandbox benchmark jobs are not published to tenants. Missing measurements remain missing; HTTP 200 is never treated as quality. The response contains no policy configuration, prompts, completions, or credentials.", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Published scorecards, possibly empty when no active serving policy has a scorecard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBenchmarkScoreList" } } } }, "400": { "description": "Authenticated tenant has no organization identity" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "Optimizer control plane is not configured" }, "503": { "description": "An active scorecard could not be read truthfully" } } } }, "/v1/benchmarks/{policy_id}": { "get": { "tags": ["benchmarks"], "operationId": "getTenantBenchmarkScore", "summary": "Retrieve one published tenant benchmark scorecard", "description": "Returns a scorecard only when the policy belongs to the authenticated tenant's project and is the active serving policy. Sibling, draft, experimenting, and sandbox benchmark-job identities return 404.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published scorecard", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "benchmark_score" }, "data": { "$ref": "#/components/schemas/TenantBenchmarkScore" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown, sibling, draft, experimenting, or unpublished policy" }, "501": { "description": "Optimizer control plane is not configured" }, "503": { "description": "The active scorecard could not be read truthfully" } } } }, "/v1/optimizer/decisions/{decision_id}/outcomes": { "get": { "tags": ["optimizer"], "operationId": "listOptimizerDecisionOutcomes", "summary": "List stored outcomes for one tenant-owned optimizer decision", "description": "Returns every persisted outcome row for a Decision the caller owns. An owned decision with no reported outcomes is HTTP 200 and an empty JSON array — never inferred task success or quality=0. A decision belonging to another tenant/project is 404, indistinguishable from an unknown id. Response items expose stored outcome fields only; internal learning stamps and reporter identity are omitted.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "decision_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stored outcomes for the decision (possibly empty)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OptimizerStoredOutcome" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown decision_id, or the decision belongs to another tenant/project" } } } }, "/v1/optimizer/decisions/{decision_id}": { "get": { "tags": ["optimizer"], "operationId": "getOptimizerDecision", "summary": "Retrieve one optimizer decision scoped to the caller's own project", "description": "Returns durable routing/bandit assignment provenance for one Decision (never raw prompt/completion bodies -- Decision never stores them). A decision belonging to another tenant/project is 404, indistinguishable from an unknown id. Response field names are the literal Go struct field names as marshaled today (no json tag renaming applied); a stable rename of a field is a breaking change under this document's versioning policy.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "decision_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Decision assignment record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizerDecision" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown decision_id, or the decision belongs to another tenant/project" } } } }, "/v1/organizations/projects": { "get": { "tags": ["identity"], "operationId": "listOrganizationProjects", "summary": "List projects in the authenticated organization", "description": "Tenant-scoped read of projects sharing the caller's organization_id. Cross-organization ids are never returned. Portal session cookies and Bearer API keys are accepted.", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Organization projects (possibly empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationProjectList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Organization identity missing on the authenticated tenant" }, "501": { "description": "Organization project catalog is not configured on this deployment" } } } }, "/v1/budgets": { "get": { "tags": ["budgets"], "operationId": "listBudgets", "summary": "List budget pools visible to the authenticated project", "description": "Tenant-scoped read of hierarchical budget pools. Returns only pools in the caller's organization whose scope matches the authenticated project and API key (organization, department, team, project, user, api_key, application). Provider/model-scoped pools are omitted unless the caller identity would match them on inference. Create/adjust/reset remain on /admin/budgets*. Public Tunnel/Worker allowlist this path.", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Visible budget pools (possibly empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetPoolList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Organization identity missing on the authenticated tenant" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/budgets/{id}": { "get": { "tags": ["budgets"], "operationId": "getBudget", "summary": "Retrieve one budget pool visible to the authenticated project", "description": "Returns one pool when it belongs to the caller's organization and matches project/api_key scope. Cross-tenant or out-of-scope ids are 404, indistinguishable from unknown.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Budget pool metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetPool" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown budget pool, or not visible to this tenant" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/budgets/{id}/usage": { "get": { "tags": ["budgets"], "operationId": "getBudgetUsage", "summary": "Current-period usage for one visible budget pool", "description": "Returns reserved and consumed micros for the pool's active period plus remaining capacity derived from the hard limit. Conversation-period pools report pool-level usage (not per-session). Cross-tenant or out-of-scope ids are 404.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Budget period usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetPoolUsage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown budget pool, or not visible to this tenant" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/budgets/{id}/alerts": { "get": { "tags": ["budgets"], "operationId": "listBudgetAlerts", "summary": "Alert history for one visible budget pool", "description": "Returns durable threshold crossings recorded for the pool's active and prior periods. Uses the same FilterPools ACL as tenant budget reads; cross-tenant or out-of-scope ids are 404. Does not imply email or webhook delivery.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Budget alert history (possibly empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetAlertList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown budget pool, or not visible to this tenant" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/notifications/budget-alerts": { "get": { "tags": ["notifications"], "operationId": "listBudgetAlertInbox", "summary": "Inbox of budget alerts across visible pools", "description": "Aggregates alert history from every budget pool visible to the authenticated project via FilterPools, sorted newest-first. Read-only view of durable budget_alerts rows; does not imply email or webhook delivery.", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Budget alert inbox (possibly empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetAlertList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/virtual-models": { "post": { "tags": ["governance"], "operationId": "createVirtualModel", "summary": "Create a tenant virtual model with its first draft", "description": "Creates a project-scoped, hidden virtual-model identity and its first draft from the authenticated portal composer. Organization and project ownership come only from the authenticated tenant session; request-body or URL tenant selection is not supported. Requires credentials.write. The draft is not active until the existing CAS activate operation is called.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantVirtualModelCreateRequest" } } } }, "responses": { "201": { "description": "Project-scoped virtual model and first draft created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantVirtualModelCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "credentials.write required" }, "409": { "description": "Virtual-model alias already exists in this project" }, "501": { "description": "Governance is not configured on this deployment" } } }, "get": { "tags": ["governance"], "operationId": "listVirtualModels", "summary": "List virtual models visible to the authenticated project", "description": "Tenant-scoped read of virtual models in the caller's organization whose project scope matches the authenticated project (org-wide models plus project-scoped models for this project). Cross-organization ids never appear. Draft/activate/rollback mutations remain on the POST paths and require credentials.write.", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Visible virtual models (possibly empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualModelList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Organization identity missing on the authenticated tenant" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/virtual-models/{id}": { "get": { "tags": ["governance"], "operationId": "getVirtualModel", "summary": "Retrieve one virtual model and its versions", "description": "Returns model metadata and every version row when the model belongs to the caller's organization and matches project scope. Cross-tenant or out-of-project ids are 404, indistinguishable from unknown.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Virtual model with versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualModelDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown virtual model, or not visible to this tenant" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/virtual-models/{id}/versions": { "post": { "tags": ["governance"], "operationId": "createVirtualModelVersion", "summary": "Create a draft virtual-model policy version", "description": "Tenant-scoped draft create for VirtualModelPolicy documents in the portal composer subset (targets with provider/account/model/priority, optional spec.request_defaults.max_tokens and spec.reasoning_mode). The saved output default applies only to chat requests for the active alias that omit max_tokens/max_completion_tokens; it is not a hard cap. reasoning_mode=disabled is enforced for the qualified single-target OpenRouter DeepSeek V4.1 Flash native contract or Bonsai2-27B/ollama-gpu local contract only. The local contract requires signed exact-body input-fit on the pinned backend build/template before generation; neither contract establishes task quality. Requires credentials.write (owner/admin). Cross-organization or out-of-project ids are 404. Admin-only controls (fallback, allowed_roles, constraints, etc.) are HTTP 400. Activation remains on POST /v1/virtual-models/{id}/activate with CAS.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualModelVersionCreateRequest" } } } }, "responses": { "201": { "description": "Draft version created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualModelVersionCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "credentials.write required" }, "404": { "description": "Unknown virtual model or not visible to this tenant" }, "409": { "description": "Version conflict" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/virtual-models/{id}/activate": { "post": { "tags": ["governance"], "operationId": "activateVirtualModelVersion", "summary": "Activate a draft virtual-model version (CAS)", "description": "Atomically activates version_id when expected_active_version_id matches the model's current active version (empty string expects none). Requires credentials.write. Stale CAS is HTTP 409.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualModelLifecycleRequest" } } } }, "responses": { "200": { "description": "Activated version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualModelVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "credentials.write required" }, "404": { "description": "Unknown virtual model, version, or not visible to this tenant" }, "409": { "description": "Version is not draft or lifecycle CAS conflict" }, "501": { "description": "Governance is not configured on this deployment" } } } }, "/v1/keys/local-model-options": { "get": { "tags": ["portal-security"], "operationId": "listKeyLocalModelOptions", "summary": "List eligible explicit-free local models for project-key allow-list edits", "description": "Requires a verified-human project owner/admin portal session and current organization MFA policy. key_id must identify an active key in the exact session project; options are evaluated against that key's persisted role and identity bindings. Generic runtime/API-key-derived sessions and bearer tokens are not accepted. Read-only and content-free; this is not a promise of hardware capacity at dispatch time.", "security": [{ "portalSession": [] }], "parameters": [{ "name": "key_id", "in": "query", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Concrete model IDs eligible for addition; existing key entries are not modified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Verified owner/admin session or policy-required MFA absent" } } } }, "/v1/keys/{key_id}/allowed-models": { "patch": { "tags": ["portal-security"], "operationId": "updateProjectKeyAllowedModels", "summary": "Add explicit-free local models or remove existing model entries from an active project key", "description": "Verified-human owner/admin portal session, allowed portal Origin, and organization MFA policy are required. Bearer/API-key-derived sessions cannot edit. expected_allowed_models must equal the current list (409 on concurrent edit). add_local_models accepts only currently eligible concrete explicit-free local IDs; unchanged aliases and paid entries remain. remove_models can only narrow an existing list and cannot make it empty, since an empty list means unrestricted. An unrestricted key remains unchanged on additions. Key secret, role, budget, rate and expiry are never changed. The key write and audit record commit atomically.", "security": [{ "portalSession": [] }], "parameters": [{ "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["expected_allowed_models", "add_local_models", "remove_models"], "properties": { "expected_allowed_models": { "type": "array", "items": { "type": "string" } }, "add_local_models": { "type": "array", "items": { "type": "string" } }, "remove_models": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Secret-free updated key metadata or unchanged unrestricted key" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Verified owner/admin session, portal Origin, or policy-required MFA absent" }, "404": { "description": "Unknown, foreign, revoked, or expired key" }, "409": { "description": "Allow-list changed concurrently; refresh and retry" } } } }, "/admin/projects/{project_id}/keys/{key_id}/allowed-models": { "patch": { "tags": ["portal-security"], "operationId": "adminUpdateProjectKeyAllowedModels", "summary": "Operator-scoped audited free-local key allow-list update", "description": "Requires the existing X-Darouter-Admin-Token; bearer authentication is rejected. The key must belong to the exact route project. Uses the same expected-list CAS, explicit-free local addition validation, narrowing-only removal, and atomic audit transaction as the owner route. No key secret, budget, or paid permission is granted.", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["expected_allowed_models", "add_local_models", "remove_models"], "properties": { "expected_allowed_models": { "type": "array", "items": { "type": "string" } }, "add_local_models": { "type": "array", "items": { "type": "string" } }, "remove_models": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Secret-free updated key metadata" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Project or key not found in exact scope" }, "409": { "description": "Allow-list changed concurrently" } } } }, "/v1/byok/credentials": { "post": { "tags": ["identity"], "operationId": "createBYOKCredential", "summary": "Create a tenant BYOK credential", "description": "Stores a provider secret write-only. `validate` defaults to `format`; `upstream` performs one bounded non-billed provider probe only when a matching provider-account egress snapshot is available. Probe failures are returned as validation classes without secret material.", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BYOKCreateRequest" } } } }, "responses": { "201": { "description": "Credential metadata; secret is never returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BYOKCredential" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "credentials.write required" }, "422": { "description": "Provider validation failed without secret material" }, "501": { "description": "BYOK storage is not configured" }, "503": { "description": "BYOK key service or egress policy unavailable" } } } }, "/v1/byok/credentials/{id}/rotate": { "post": { "tags": ["identity"], "operationId": "rotateBYOKCredential", "summary": "Rotate a tenant BYOK credential", "description": "Replaces a provider secret write-only. `validate` defaults to `format`; `upstream` performs one bounded non-billed provider probe against the existing credential's provider-account egress snapshot before mutation.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BYOKRotateRequest" } } } }, "responses": { "200": { "description": "Rotated credential metadata; secret is never returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BYOKCredential" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "credentials.write required" }, "404": { "description": "Credential is not visible to this tenant" }, "409": { "description": "Credential is revoked or revision conflict" }, "422": { "description": "Provider validation failed without secret material" }, "503": { "description": "BYOK key service or egress policy unavailable" } } } }, "/v1/virtual-models/{id}/rollback": { "post": { "tags": ["governance"], "operationId": "rollbackVirtualModelVersion", "summary": "Rollback to a retired virtual-model version (CAS)", "description": "Reactivates a retired version_id when expected_active_version_id matches the current active version. Requires credentials.write. Stale CAS is HTTP 409.", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualModelLifecycleRequest" } } } }, "responses": { "200": { "description": "Reactivated version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualModelVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "credentials.write required" }, "404": { "description": "Unknown virtual model, version, or not visible to this tenant" }, "409": { "description": "Version is not retired or lifecycle CAS conflict" }, "501": { "description": "Governance is not configured on this deployment" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Darouter tenant API key (dar_*), HS256 JWT (DAROUTER_JWT_*), or RS256/ES256 JWT verified via a registered JWKS trust (PUT /admin/jwt-bearer/trusts, #1024). JWKS mode requires iss/aud match, allowed alg, finite exp, and clock-skew bounds; failures are 401 without echoing the token." }, "xApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Anthropic-shaped tenant key on /v1/messages" }, "xGoogApiKey": { "type": "apiKey", "in": "header", "name": "x-goog-api-key", "description": "Gemini-shaped tenant key on generateContent. Query ?key= is rejected." }, "portalSession": { "type": "apiKey", "in": "cookie", "name": "darouter_portal_session", "description": "HttpOnly portal session cookie issued by POST /portal/session" } }, "responses": { "Unauthorized": { "description": "Missing or invalid tenant credential" }, "BadRequest": { "description": "Unknown or unpreserved field, or capability missing" }, "NotFound": { "description": "Resource not found or not owned by the authenticated subject" } }, "schemas": { "EvaluationProvenance": { "type": "object", "required": ["source", "license", "privacy_class", "revision"], "additionalProperties": false, "properties": { "source": { "type": "string", "maxLength": 256 }, "license": { "type": "string", "maxLength": 128 }, "privacy_class": { "type": "string", "maxLength": 64 }, "revision": { "type": "string", "maxLength": 128 }, "metadata": { "type": "object" } } }, "EvaluationDatasetRow": { "type": "object", "required": ["input", "target"], "additionalProperties": false, "properties": { "input": { "type": "object" }, "target": { "type": "object" }, "metadata": { "type": "object" } } }, "EvaluationDatasetVersionInput": { "type": "object", "required": ["id", "version", "rows", "provenance"], "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 128 }, "version": { "type": "integer", "minimum": 1 }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationDatasetRow" } }, "provenance": { "$ref": "#/components/schemas/EvaluationProvenance" } } }, "EvaluationDatasetVersion": { "allOf": [ { "$ref": "#/components/schemas/EvaluationDatasetVersionInput" }, { "type": "object", "required": ["object", "hash", "created_at"], "properties": { "object": { "type": "string" }, "hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } ] }, "EvaluationDatasetVersionList": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationDatasetVersion" } } } }, "EvaluationEvaluatorVersionInput": { "type": "object", "required": ["id", "version", "definition", "provenance"], "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 128 }, "version": { "type": "integer", "minimum": 1 }, "definition": { "type": "object" }, "provenance": { "$ref": "#/components/schemas/EvaluationProvenance" } } }, "EvaluationEvaluatorVersion": { "allOf": [ { "$ref": "#/components/schemas/EvaluationEvaluatorVersionInput" }, { "type": "object", "required": ["object", "hash", "created_at"], "properties": { "object": { "type": "string" }, "hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } ] }, "EvaluationEvaluatorVersionList": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationEvaluatorVersion" } } } }, "EvaluationExperimentInput": { "type": "object", "required": ["id", "dataset_id", "dataset_version", "evaluator_id", "evaluator_version", "policy_id", "candidate_version_id", "control_version_id", "mode"], "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 128 }, "dataset_id": { "type": "string", "maxLength": 128 }, "dataset_version": { "type": "integer", "minimum": 1 }, "evaluator_id": { "type": "string", "maxLength": 128 }, "evaluator_version": { "type": "integer", "minimum": 1 }, "policy_id": { "type": "string" }, "candidate_version_id": { "type": "string" }, "control_version_id": { "type": "string" }, "mode": { "type": "string", "enum": ["offline", "shadow"] } } }, "EvaluationEvidence": { "type": "object", "additionalProperties": false, "properties": { "sample_count": { "type": "integer", "minimum": 0 }, "outcome_count": { "type": "integer", "minimum": 0 }, "outcome_coverage": { "type": "number", "minimum": 0, "maximum": 1 }, "candidate_quality": { "type": "number" }, "control_quality": { "type": "number" }, "quality_lower_bound": { "type": "number" }, "candidate_cost": { "type": "number", "minimum": 0 }, "control_cost": { "type": "number", "minimum": 0 }, "candidate_latency": { "type": "number", "minimum": 0 }, "control_latency": { "type": "number", "minimum": 0 }, "candidate_error_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "control_error_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "uncertainty": { "type": "number", "minimum": 0 }, "observed_at": { "type": "string", "format": "date-time" }, "feedback_bindings": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationFeedbackBinding" } } } }, "EvaluationFeedbackBinding": { "type": "object", "required": ["decision_id", "attempt_id", "idempotency_key", "success"], "additionalProperties": false, "properties": { "decision_id": { "type": "string" }, "attempt_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "success": { "type": "boolean" }, "quality_score": { "type": "number" }, "user_feedback": { "type": "object", "additionalProperties": true }, "task_metrics": { "type": "object", "additionalProperties": true }, "reported_at": { "type": "string", "format": "date-time" } } }, "EvaluationGate": { "type": "object", "required": ["min_sample_count", "min_outcome_count", "min_outcome_coverage", "max_quality_regression", "max_cost_regression", "max_latency_regression", "max_error_rate", "max_uncertainty"], "additionalProperties": false, "properties": { "min_sample_count": { "type": "integer", "minimum": 1 }, "min_outcome_count": { "type": "integer", "minimum": 1 }, "min_outcome_coverage": { "type": "number", "minimum": 0, "maximum": 1 }, "max_quality_regression": { "type": "number", "minimum": 0 }, "max_cost_regression": { "type": "number", "minimum": 0 }, "max_latency_regression": { "type": "number", "minimum": 0 }, "max_error_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "max_uncertainty": { "type": "number", "minimum": 0 } } }, "EvaluationDecisionInput": { "type": "object", "required": ["evidence", "gate"], "additionalProperties": false, "properties": { "evidence": { "$ref": "#/components/schemas/EvaluationEvidence" }, "gate": { "$ref": "#/components/schemas/EvaluationGate" } } }, "EvaluationExperiment": { "type": "object", "required": ["id", "organization_id", "project_id", "dataset_id", "dataset_version", "evaluator_id", "evaluator_version", "policy_id", "candidate_version_id", "control_version_id", "mode", "status", "evidence", "gate", "created_at", "updated_at"], "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "project_id": { "type": "string" }, "dataset_id": { "type": "string" }, "dataset_version": { "type": "integer" }, "evaluator_id": { "type": "string" }, "evaluator_version": { "type": "integer" }, "policy_id": { "type": "string" }, "candidate_version_id": { "type": "string" }, "control_version_id": { "type": "string" }, "mode": { "type": "string" }, "status": { "type": "string" }, "evidence": { "$ref": "#/components/schemas/EvaluationEvidence" }, "gate": { "$ref": "#/components/schemas/EvaluationGate" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EvaluationExperimentList": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationExperiment" } } } }, "BYOKValidationMode": { "type": "string", "enum": ["format", "upstream"], "default": "format", "description": "Format-only validation by default; upstream performs one bounded non-billed probe against an approved provider-account egress snapshot." }, "BYOKCreateRequest": { "type": "object", "additionalProperties": false, "required": ["provider", "secret"], "properties": { "provider": { "type": "string", "minLength": 1 }, "secret": { "type": "string", "writeOnly": true, "minLength": 1 }, "idempotency_key": { "type": "string" }, "validate": { "$ref": "#/components/schemas/BYOKValidationMode" }, "validation_timeout_ms": { "type": "integer", "minimum": 0, "maximum": 30000, "default": 5000, "description": "Upstream probe timeout; ignored for format validation." } } }, "BYOKRotateRequest": { "type": "object", "additionalProperties": false, "required": ["secret"], "properties": { "secret": { "type": "string", "writeOnly": true, "minLength": 1 }, "idempotency_key": { "type": "string" }, "validate": { "$ref": "#/components/schemas/BYOKValidationMode" }, "validation_timeout_ms": { "type": "integer", "minimum": 0, "maximum": 30000, "default": 5000, "description": "Upstream probe timeout; ignored for format validation." } } }, "BYOKCredential": { "type": "object", "additionalProperties": false, "required": ["object", "id", "provider", "credential_ref", "credential_version", "status", "validation_class"], "properties": { "object": { "type": "string", "const": "byok.credential" }, "id": { "type": "string" }, "provider": { "type": "string" }, "credential_ref": { "type": "string", "description": "Opaque reference; never a secret." }, "credential_version": { "type": "string" }, "status": { "type": "string", "enum": ["active", "revoked"] }, "validation_class": { "type": "string", "enum": ["ok", "auth", "scope", "quota", "transient", "invalid"] }, "created_at": { "type": "string", "format": "date-time" }, "rotated_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time" } } }, "PortalMFACode": { "type": "object", "required": ["code"], "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 32 } } }, "SignupRequest": { "type": "object", "additionalProperties": false, "required": ["email"], "properties": { "organization": { "type": "string", "maxLength": 64 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "invite_code": { "type": "string" } } }, "SignupResponse": { "type": "object", "additionalProperties": false, "required": ["project_id", "key_id", "api_key", "monthly_budget_cents", "contact_email_verified"], "properties": { "project_id": { "type": "string" }, "key_id": { "type": "string" }, "api_key": { "type": "string", "description": "New project API key; returned once." }, "monthly_budget_cents": { "type": "integer", "format": "int64" }, "contact_email_verified": { "type": "boolean", "const": false } } }, "ContactEmailVerifyRequest": { "type": "object", "additionalProperties": false, "required": ["token"], "properties": { "token": { "type": "string", "writeOnly": true } } }, "ContactEmailResendRequest": { "type": "object", "additionalProperties": false, "required": ["email"], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 } } }, "ContactEmailVerificationResponse": { "type": "object", "additionalProperties": false, "required": ["object", "verified"], "properties": { "object": { "type": "string", "const": "contact_email.verification" }, "verified": { "type": "boolean", "const": true } } }, "ContactEmailResendResponse": { "type": "object", "additionalProperties": false, "required": ["object", "accepted", "message"], "properties": { "object": { "type": "string", "const": "contact_email.verification" }, "accepted": { "type": "boolean", "const": true }, "message": { "type": "string" } } }, "ModelList": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "Model": { "type": "object", "required": ["id", "object"], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "model" }, "owned_by": { "type": "string" } } }, "ChatRequest": { "type": "object", "required": ["messages"], "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "stream": { "type": "boolean" }, "temperature": { "type": "number" }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "top_k": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Anthropic top_k / Gemini topK / Runpod sampling_params.top_k; OpenAI-compatible and Azure are HTTP 400. Not a search_space overlay." }, "frequency_penalty": { "type": "number", "minimum": -2, "maximum": 2 }, "presence_penalty": { "type": "number", "minimum": -2, "maximum": 2 }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number", "minimum": -100, "maximum": 100 }, "description": "Token-id biases forwarded by OpenAI-compatible, Azure, and Runpod adapters; Anthropic and Gemini are HTTP 400" }, "n": { "type": "integer", "minimum": 1, "maximum": 1, "description": "OpenAI n; only 1 is accepted until multi-choice responses are implemented" }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "OpenAI seed forwarded by OpenAI-compatible, Azure, Gemini, and Runpod adapters; Anthropic is HTTP 400. Opt-in search_space may overlay it." }, "logprobs": { "type": "boolean", "description": "OpenAI logprobs forwarded by OpenAI-compatible and Azure adapters; Anthropic, Gemini, and Runpod are HTTP 400. Not a search_space overlay." }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Requires logprobs=true. Number of most likely tokens to return at each position." }, "reasoning_effort": { "type": "string", "enum": ["none", "minimal", "low", "medium", "high", "xhigh"], "description": "OpenAI reasoning_effort forwarded by OpenAI-compatible and Azure adapters; Anthropic, Gemini, and Runpod are HTTP 400. Responses uses reasoning.effort." }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 4 } ] }, "response_format": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["text", "json_object", "json_schema"] }, "json_schema": { "type": "object", "required": ["name", "schema"], "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "schema": { "type": "object" }, "strict": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false }, "max_tokens": { "type": "integer" }, "tools": { "type": "array", "items": { "type": "object" } }, "tool_choice": {}, "parallel_tool_calls": { "type": "boolean" }, "prompt_cache_key": { "type": "string", "maxLength": 1024, "description": "Forwarded only by OpenAI-compatible adapters; others are HTTP 400" }, "user": { "type": "string", "maxLength": 256, "description": "OpenAI end-user identifier forwarded by OpenAI-compatible and Azure adapters as user, and by Anthropic as metadata.user_id; Gemini and Runpod are HTTP 400. Not used in exact-cache keys." }, "service_tier": { "type": "string", "enum": ["standard", "flex", "priority", "batch"] }, "tags": { "type": "array", "items": { "type": "string" } } } }, "ChatMessage": { "type": "object", "required": ["role"], "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object" } }, "tool_call_id": { "type": "string" } } }, "ChatResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object" } }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "prompt_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer" } } } } }, "EmbeddingRequest": { "type": "object", "required": ["input"], "properties": { "model": { "type": "string" }, "input": {}, "encoding_format": { "type": "string" }, "dimensions": { "type": "integer" } } }, "ModerationRequest": { "type": "object", "required": ["input"], "properties": { "model": { "type": "string" }, "input": { "description": "A string, an array of strings, or an array of OpenAI multi-modal moderation content parts. Forwarded byte-for-byte; not parsed or validated by Darouter." } } }, "ImageGenerationRequest": { "type": "object", "required": ["prompt"], "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "n": { "type": "integer" }, "size": { "type": "string" }, "quality": { "type": "string" }, "style": { "type": "string" }, "response_format": { "type": "string" }, "user": { "type": "string" } } }, "SpeechRequest": { "type": "object", "required": ["input"], "properties": { "model": { "type": "string" }, "input": { "type": "string" }, "voice": { "type": "string" }, "response_format": { "type": "string" }, "speed": { "type": "number" } } }, "RerankRequest": { "type": "object", "required": ["query", "documents"], "properties": { "model": { "type": "string" }, "query": { "type": "string" }, "documents": { "type": "array", "items": { "type": "string" } }, "top_n": { "type": "integer" } } }, "OptimizerOutcomeUserFeedback": { "type": "object", "description": "Content-free allowlisted scalars only (issue #381). Unknown keys, nested objects, and prompt/response/credential-shaped keys or string values are rejected with 400.", "additionalProperties": false, "maxProperties": 8, "properties": { "rating": { "type": "number" }, "thumbs_up": { "type": "boolean" }, "comment_hash": { "type": "string", "maxLength": 64 } } }, "OptimizerOutcomeTaskMetrics": { "type": "object", "description": "Content-free allowlisted scalars only (issue #381). Unknown keys, nested objects, and prompt/response/credential-shaped keys or string values are rejected with 400.", "additionalProperties": false, "maxProperties": 8, "properties": { "latency_ms": { "type": "number" }, "tokens": { "type": "number" }, "cost_usd": { "type": "number" }, "ttft_ms": { "type": "number" }, "cache_hit": { "type": "boolean" }, "tool_call_valid": { "type": "boolean" }, "error_class": { "type": "string", "maxLength": 64 }, "game_build_passed": { "type": "boolean" }, "game_browser_play_passed": { "type": "boolean" }, "game_novelty_passed": { "type": "boolean" }, "game_polish_passed": { "type": "boolean" }, "game_refinement_passed": { "type": "boolean" }, "game_repair_rounds": { "type": "integer", "minimum": 0, "maximum": 1000 } } }, "OptimizerOutcomeRequest": { "type": "object", "required": ["decision_id", "idempotency_key"], "properties": { "decision_id": { "type": "string", "description": "Must be a decision previously recorded for the caller's own project; otherwise 404." }, "idempotency_key": { "type": "string", "description": "Idempotent replay key scoped to decision_id. A conflicting payload for an existing key is 409." }, "source": { "type": "string", "enum": ["application", "user", "test", "rule", "verifier", "judge_model", "human", "synthetic"], "description": "Tenant API keys may only submit application/user/rule/judge_model/synthetic/test; human/verifier are 403 on this endpoint (use POST /admin/optimizer/outcomes). Missing or unrecognized values are 400." }, "success": { "type": "boolean" }, "reward": { "type": "number", "nullable": true }, "quality_score": { "type": "number", "nullable": true }, "business_value": { "type": "number", "nullable": true }, "user_feedback": { "$ref": "#/components/schemas/OptimizerOutcomeUserFeedback" }, "task_metrics": { "$ref": "#/components/schemas/OptimizerOutcomeTaskMetrics" }, "evaluator_id": { "type": "string" }, "evaluator_version": { "type": "string" } } }, "OptimizerOutcomeResponse": { "type": "object", "required": ["accepted", "duplicate"], "properties": { "accepted": { "type": "boolean" }, "duplicate": { "type": "boolean", "description": "true when idempotency_key was already recorded with the same payload" } } }, "OptimizerStoredOutcome": { "type": "object", "description": "One persisted optimizer outcome row returned by GET /v1/optimizer/decisions/{decision_id}/outcomes. Success/quality_score are stored reporter signals only. Known Verse source/build milestones are labeled stage_only and excluded from task-success learning; HTTP 200 on the list is not task success and quality is never invented when the array is empty.", "required": ["id", "decision_id", "source", "success", "idempotency_key", "reported_at"], "properties": { "id": { "type": "string" }, "decision_id": { "type": "string" }, "outcome_key": { "type": "string" }, "source": { "type": "string", "enum": ["application", "user", "test", "rule", "verifier", "judge_model", "human", "synthetic"] }, "success": { "type": "boolean" }, "reward": { "type": "number", "nullable": true }, "quality_score": { "type": "number", "nullable": true }, "business_value": { "type": "number", "nullable": true }, "user_feedback": { "$ref": "#/components/schemas/OptimizerOutcomeUserFeedback" }, "task_metrics": { "$ref": "#/components/schemas/OptimizerOutcomeTaskMetrics" }, "task_stage": { "type": "string", "enum": ["source", "build", "browser_play"], "description": "Content-free derived stage label when recognized." }, "stage_only": { "type": "boolean", "description": "True for recognized source/build milestones, which are audit-only and not game-task wins." }, "evaluator_id": { "type": "string" }, "evaluator_version": { "type": "string" }, "idempotency_key": { "type": "string" }, "reported_at": { "type": "string", "format": "date-time" } } }, "OptimizerRoutingAggregateSlice": { "type": "object", "additionalProperties": false, "description": "Counters for one aggregates slice. winner_cost_micros sums won attempts only. decisions_missing_outcome is not quality=0.", "properties": { "decision_count": { "type": "integer", "format": "int64" }, "decisions_with_outcome": { "type": "integer", "format": "int64" }, "decisions_missing_outcome": { "type": "integer", "format": "int64" }, "winner_cost_micros": { "type": "integer", "format": "int64" }, "error_decision_count": { "type": "integer", "format": "int64" }, "hedge_or_fallback_decision_count": { "type": "integer", "format": "int64" }, "cache_hit_decision_count": { "type": "integer", "format": "int64" }, "latency_mean_ms": { "type": "number", "nullable": true }, "ttft_mean_ms": { "type": "number", "nullable": true }, "ttft_sample_count": { "type": "integer", "format": "int64" }, "hedge_attempt_count": { "type": "integer", "format": "int64" }, "fallback_attempt_count": { "type": "integer", "format": "int64" } } }, "OptimizerRoutingAggregateModelRow": { "type": "object", "additionalProperties": false, "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "decision_count": { "type": "integer", "format": "int64" }, "decisions_with_outcome": { "type": "integer", "format": "int64" }, "decisions_missing_outcome": { "type": "integer", "format": "int64" }, "winner_cost_micros": { "type": "integer", "format": "int64" }, "error_decision_count": { "type": "integer", "format": "int64" }, "hedge_or_fallback_decision_count": { "type": "integer", "format": "int64" }, "cache_hit_decision_count": { "type": "integer", "format": "int64" }, "latency_mean_ms": { "type": "number", "nullable": true }, "ttft_mean_ms": { "type": "number", "nullable": true }, "ttft_sample_count": { "type": "integer", "format": "int64" }, "hedge_attempt_count": { "type": "integer", "format": "int64" }, "fallback_attempt_count": { "type": "integer", "format": "int64" } } }, "OptimizerRoutingAggregateBucket": { "type": "object", "additionalProperties": false, "properties": { "bucket_start": { "type": "string", "format": "date-time" }, "decision_count": { "type": "integer", "format": "int64" }, "decisions_with_outcome": { "type": "integer", "format": "int64" }, "decisions_missing_outcome": { "type": "integer", "format": "int64" }, "winner_cost_micros": { "type": "integer", "format": "int64" }, "error_decision_count": { "type": "integer", "format": "int64" }, "hedge_or_fallback_decision_count": { "type": "integer", "format": "int64" }, "cache_hit_decision_count": { "type": "integer", "format": "int64" }, "latency_mean_ms": { "type": "number", "nullable": true }, "ttft_mean_ms": { "type": "number", "nullable": true }, "ttft_sample_count": { "type": "integer", "format": "int64" }, "hedge_attempt_count": { "type": "integer", "format": "int64" }, "fallback_attempt_count": { "type": "integer", "format": "int64" } } }, "OptimizerRoutingAggregates": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true }, "bucket": { "type": "string" }, "summary": { "$ref": "#/components/schemas/OptimizerRoutingAggregateSlice" }, "by_model": { "type": "array", "items": { "$ref": "#/components/schemas/OptimizerRoutingAggregateModelRow" } }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/OptimizerRoutingAggregateBucket" } }, "truncated": { "type": "boolean" } } }, "UsageExportJob": { "type": "object", "additionalProperties": false, "required": ["object", "id", "status", "format", "bucket", "from", "to", "as_of", "expires_at"], "properties": { "object": { "type": "string", "const": "usage_export" }, "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "running", "succeeded", "failed", "expired"] }, "format": { "type": "string", "enum": ["json", "csv"] }, "bucket": { "type": "string", "enum": ["day", "hour"] }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "as_of": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "download_url": { "type": "string" }, "error_code": { "type": "string" } } }, "TenantUsageSeries": { "type": "object", "additionalProperties": false, "required": ["object", "source", "freshness", "quality", "from", "to", "bucket", "latency_available", "latency_note", "series", "truncated"], "properties": { "object": { "type": "string", "const": "usage_series" }, "source": { "type": "string", "const": "provider_billable_events" }, "freshness": { "type": "string", "const": "durable" }, "quality": { "type": "boolean", "const": false }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "bucket": { "type": "string", "enum": ["day", "hour"] }, "latency_available": { "type": "boolean" }, "latency_note": { "type": "string" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/TenantUsageSeriesPoint" } }, "truncated": { "type": "boolean" } } }, "TenantUsageSeriesPoint": { "type": "object", "additionalProperties": false, "required": ["bucket_start", "request_count", "provider_attempts", "successful_requests", "spend_micros", "by_provider"], "properties": { "bucket_start": { "type": "string", "format": "date-time" }, "request_count": { "type": "integer", "format": "int64" }, "provider_attempts": { "type": "integer", "format": "int64" }, "successful_requests": { "type": "integer", "format": "int64" }, "spend_micros": { "type": "integer", "format": "int64" }, "by_provider": { "type": "array", "items": { "$ref": "#/components/schemas/TenantUsageSeriesProvider" } }, "latency_mean_ms": { "type": "number", "nullable": true } } }, "TenantUsageSeriesProvider": { "type": "object", "additionalProperties": false, "required": ["provider", "attempts", "spend_micros"], "properties": { "provider": { "type": "string" }, "attempts": { "type": "integer", "format": "int64" }, "spend_micros": { "type": "integer", "format": "int64" } } }, "TenantBenchmarkScoreList": { "type": "object", "additionalProperties": false, "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "benchmark_score_list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TenantBenchmarkScore" } } } }, "TenantBenchmarkScore": { "type": "object", "additionalProperties": false, "required": ["policy_id", "version", "published", "source", "scorecard", "models"], "properties": { "policy_id": { "type": "string" }, "policy_name": { "type": "string" }, "task_type": { "type": "string" }, "version": { "type": "integer" }, "published": { "type": "boolean", "const": true }, "source": { "type": "string", "const": "active_serving_policy" }, "scorecard": { "$ref": "#/components/schemas/ScorecardReport" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/TenantBenchmarkModelReference" } } } }, "TenantBenchmarkModelReference": { "type": "object", "additionalProperties": false, "required": ["arm_id", "is_control"], "properties": { "arm_id": { "type": "string" }, "arm_name": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_control": { "type": "boolean" } } }, "ScorecardReport": { "type": "object", "additionalProperties": false, "required": ["schema_version", "kind", "min_samples", "confidence", "outlier_iqr_k", "dimensions", "arms", "signals", "definition_hash", "routing_enabled", "max_age_seconds", "computed_at", "promotes", "http_success_used", "reason"], "properties": { "schema_version": { "type": "integer" }, "kind": { "type": "string" }, "min_samples": { "type": "integer" }, "confidence": { "type": "number" }, "outlier_iqr_k": { "type": "number" }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreDimensionSpec" } }, "arms": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardArm" } }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreSignal" } }, "definition_hash": { "type": "string" }, "routing_enabled": { "type": "boolean" }, "max_age_seconds": { "type": "integer" }, "computed_at": { "type": "string", "format": "date-time" }, "promotes": { "type": "boolean", "const": false }, "http_success_used": { "type": "boolean", "const": false }, "reason": { "type": "string" } } }, "ScoreDimensionSpec": { "type": "object", "additionalProperties": false, "required": ["name", "unit", "direction", "role"], "properties": { "name": { "type": "string" }, "unit": { "type": "string" }, "direction": { "type": "string" }, "role": { "type": "string" } } }, "ScorecardArm": { "type": "object", "additionalProperties": false, "required": ["arm_id", "is_control", "eligible", "scores"], "properties": { "arm_id": { "type": "string" }, "arm_name": { "type": "string" }, "is_control": { "type": "boolean" }, "eligible": { "type": "boolean" }, "ineligible_reason": { "type": "string" }, "routing_exclusion": { "type": "string" }, "scores": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ScoreMeasurement" } }, "vs_control": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreComparison" } } } }, "ScoreMeasurement": { "type": "object", "additionalProperties": false, "required": ["name", "unit", "direction", "role", "n", "missing_n", "censored_n", "outlier_n", "usable"], "properties": { "name": { "type": "string" }, "unit": { "type": "string" }, "direction": { "type": "string" }, "role": { "type": "string" }, "n": { "type": "integer" }, "missing_n": { "type": "integer" }, "censored_n": { "type": "integer" }, "outlier_n": { "type": "integer" }, "mean": { "type": "number", "nullable": true }, "low": { "type": "number", "nullable": true }, "high": { "type": "number", "nullable": true }, "usable": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "ScoreComparison": { "type": "object", "additionalProperties": false, "required": ["dimension", "status"], "properties": { "dimension": { "type": "string" }, "diff": { "type": "number", "nullable": true }, "low": { "type": "number", "nullable": true }, "high": { "type": "number", "nullable": true }, "status": { "type": "string" } } }, "ScoreSignal": { "type": "object", "additionalProperties": false, "required": ["arm_id", "definition_hash", "schema_version", "eligible", "visibility"], "properties": { "arm_id": { "type": "string" }, "definition_hash": { "type": "string" }, "schema_version": { "type": "integer" }, "eligible": { "type": "boolean" }, "exclusion_reason": { "type": "string" }, "visibility": { "type": "string" } } }, "OptimizerDecision": { "type": "object", "additionalProperties": false, "description": "Durable routing/bandit assignment provenance plus every launched attempt and outcome presence. features/constraints are content-free classifier/bandit-context maps, never raw prompt or completion text. outcome_presence is missing or reported only; success/quality_score are never invented from HTTP 200. winner_cost_micros sums cost_micros for attempts with won=true (do not treat the sum of all attempt costs as customer-billed). Since OpenAPI 1.1.0-preview, this response uses only the documented snake_case names; the earlier incidental Go field-name shape has no aliases.", "properties": { "id": { "type": "string" }, "request_id": { "type": "string" }, "organization_id": { "type": "string" }, "project_id": { "type": "string" }, "api_key_id": { "type": "string" }, "policy_id": { "type": "string" }, "policy_version_id": { "type": "string" }, "arm_id": { "type": "string" }, "assignment_unit_hash": { "type": "string" }, "task_type": { "type": "string" }, "feature_schema_version": { "type": "integer" }, "features": { "type": "object", "nullable": true }, "constraints": { "type": "object", "nullable": true }, "propensity": { "type": "number" }, "is_holdout": { "type": "boolean" }, "session_id_hash": { "type": "string" }, "trace_id": { "type": "string" }, "assignment_mode": { "type": "string" }, "assignment_seed_hash": { "type": "string" }, "posterior_revision": { "type": "integer" }, "exploration_epoch": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/OptimizerAttempt" } }, "outcome_presence": { "type": "string", "enum": ["missing", "reported"] }, "non_learning_reason": { "type": "string" }, "winner_cost_micros": { "type": "integer", "format": "int64" } } }, "OptimizerAttempt": { "type": "object", "additionalProperties": false, "description": "One launched attempt for a decision (primary, cascade_step, hedge, canceled). HTTP 200 on an attempt is not task success.", "properties": { "id": { "type": "string" }, "decision_id": { "type": "string" }, "attempt_index": { "type": "integer" }, "arm_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "execution_mode": { "type": "string" }, "won": { "type": "boolean" }, "status": { "type": "string" }, "cost_micros": { "type": "integer", "format": "int64" }, "cost_source": { "type": "string", "enum": ["", "provider_reported", "catalog_estimate", "reservation_estimate"], "description": "Provenance of cost_micros. Empty means unavailable on older records; never infer zero or an actual provider charge." }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer", "nullable": true, "description": "Provider-reported subset of completion_tokens; null means unavailable, not zero." }, "finish_reason": { "type": "string", "enum": ["", "stop", "length", "content_filter", "tool_calls"], "description": "Provider terminal cause; empty means unavailable. length is an output limit, not application success." }, "latency_ms": { "type": "integer", "nullable": true }, "tool_call_valid": { "type": "boolean", "nullable": true }, "cache_status": { "type": "string" }, "canceled_reason": { "type": "string", "description": "Bounded cancellation cause: client_disconnect, timeout, governance, user_abort, or hedge_loser. Legacy transport-only values remain readable.", "enum": ["", "client_disconnect", "timeout", "governance", "user_abort", "hedge_loser", "canceled_before_send", "canceled_in_flight", "response_discarded"] }, "cancellation_detail": { "type": "string", "description": "Transport detail used for liability: canceled_before_send, canceled_in_flight, or response_discarded." }, "ttft_ms": { "type": "integer", "nullable": true } } }, "BudgetPool": { "type": "object", "required": ["id", "organization_id", "name", "scope_type", "scope_id", "currency", "hard_limit_usd", "hard_limit_micros", "period_type", "status"], "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "name": { "type": "string" }, "scope_type": { "type": "string" }, "scope_id": { "type": "string" }, "currency": { "type": "string" }, "hard_limit_usd": { "type": "number" }, "hard_limit_micros": { "type": "integer", "format": "int64" }, "soft_limit_usd": { "type": "number" }, "period_type": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "status": { "type": "string" } } }, "OrganizationProject": { "type": "object", "required": ["object", "id", "organization_id", "name"], "properties": { "object": { "type": "string", "const": "organization.project" }, "id": { "type": "string" }, "organization_id": { "type": "string" }, "name": { "type": "string" } } }, "OrganizationProjectList": { "type": "object", "required": ["object", "organization_id", "data"], "properties": { "object": { "type": "string", "const": "list" }, "organization_id": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationProject" } } } }, "BudgetPoolList": { "type": "object", "required": ["object", "data", "supported_period_types"], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetPool" } }, "supported_period_types": { "type": "array", "items": { "type": "string" } } } }, "BudgetPoolUsage": { "type": "object", "required": ["budget_pool_id", "reserved_usd", "consumed_usd", "reserved_micros", "consumed_micros", "remaining_usd", "remaining_micros", "hard_limit_usd", "hard_limit_micros"], "properties": { "budget_pool_id": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "reserved_usd": { "type": "number" }, "consumed_usd": { "type": "number" }, "reserved_micros": { "type": "integer", "format": "int64" }, "consumed_micros": { "type": "integer", "format": "int64" }, "remaining_usd": { "type": "number" }, "remaining_micros": { "type": "integer", "format": "int64" }, "hard_limit_usd": { "type": "number" }, "hard_limit_micros": { "type": "integer", "format": "int64" } } }, "BudgetAlert": { "type": "object", "required": ["id", "budget_pool_id", "threshold_percent", "kind", "fired_at", "period_start"], "properties": { "id": { "type": "string" }, "budget_pool_id": { "type": "string" }, "threshold_percent": { "type": "integer" }, "kind": { "type": "string", "enum": ["soft_limit", "hard_percent"] }, "fired_at": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" } } }, "BudgetAlertList": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetAlert" } } } }, "VirtualModel": { "type": "object", "required": ["id", "organization_id", "alias", "status", "active_version_id"], "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "project_id": { "type": "string" }, "alias": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "visibility": { "type": "string" }, "cost_class": { "type": "string" }, "quality_class": { "type": "string" }, "data_handling_class": { "type": "string" }, "active_version_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "VirtualModelList": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualModel" } } } }, "VirtualModelDetail": { "allOf": [ { "$ref": "#/components/schemas/VirtualModel" }, { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualModelVersion" } } } } ] }, "TenantVirtualModelCreateRequest": { "type": "object", "required": ["alias", "policy"], "additionalProperties": false, "properties": { "alias": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string" }, "policy": { "type": "object", "description": "Validated VirtualModelPolicy document from the tenant composer" } } }, "TenantVirtualModelCreateResponse": { "type": "object", "required": ["model", "version", "targets"], "properties": { "model": { "$ref": "#/components/schemas/VirtualModel" }, "version": { "$ref": "#/components/schemas/VirtualModelVersion" }, "targets": { "type": "array", "items": { "type": "object" } } } }, "VirtualModelVersionCreateRequest": { "type": "object", "required": ["policy"], "properties": { "policy": { "type": "object", "description": "Validated VirtualModelPolicy document in the tenant composer subset; spec.request_defaults.max_tokens is an optional positive-integer request default, not a hard cap. Optional spec.reasoning_mode=disabled enforces the qualified single-target OpenRouter deepseek/deepseek-v4.1-flash or Bonsai2-27B/ollama-gpu native adapter contract. The local contract additionally requires signed exact-body input-fit on the pinned backend build/template before generation; unsupported modes or targets fail closed." } } }, "VirtualModelVersionCreateResponse": { "type": "object", "required": ["version", "targets"], "properties": { "version": { "$ref": "#/components/schemas/VirtualModelVersion" }, "targets": { "type": "array", "items": { "type": "object" } } } }, "VirtualModelLifecycleRequest": { "type": "object", "required": ["version_id", "expected_active_version_id"], "properties": { "version_id": { "type": "string" }, "expected_active_version_id": { "type": "string", "description": "Compare-and-swap guard on virtual_models.active_version_id; empty string expects none" }, "reason": { "type": "string" } } }, "VirtualModelVersion": { "type": "object", "required": ["id", "virtual_model_id", "version", "status"], "properties": { "id": { "type": "string" }, "virtual_model_id": { "type": "string" }, "version": { "type": "integer" }, "artifact_hash": { "type": "string" }, "policy": { "type": "object" }, "status": { "type": "string", "enum": ["draft", "active", "retired", "disabled"] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "activated_at": { "type": "string", "format": "date-time" }, "retired_at": { "type": "string", "format": "date-time" } } } } } }