{"openapi":"3.1.0","info":{"title":"SandBase API","description":"SandBase is an agent-native platform for connecting Agents to the real world.\nUse one account and one key to call Models, ready-made APIs, and Agents.\n\n## Authentication\nPublic API requests require a SandBase API key. Use `Authorization: Bearer sk-YOUR_KEY` by default.\nAnthropic Messages and Google Gemini-compatible operations also document their native SDK-compatible key locations.\n\n## SDK Compatibility\n- **LLM Gateway** (`/v1/chat/completions`): Use OpenAI SDK with `base_url=\"https://api.sandbase.ai/v1\"`\n- **Embeddings** (`/v1/embeddings`): Use OpenAI SDK with `base_url=\"https://api.sandbase.ai/v1\"`\n- **Images** (`/v1/images/generations`, `/v1/images/edits`): Use OpenAI SDK with `base_url=\"https://api.sandbase.ai/v1\"`\n- **Anthropic Messages** (`/v1/messages`): Use Anthropic SDK with `base_url=\"https://api.sandbase.ai\"`\n- **Google Gemini GenerateContent** (`/v1beta/models/{model}:generateContent`): Configure the Google Gen AI SDK to use `https://api.sandbase.ai`\n- **Agents and Sessions** (`/v1/agents`, `/v1/agents/sessions`): Follow the OpenAI Agents protocol (`OpenAI-Beta: agents=v1` is optional) plus the documented SandBase extensions\n- **Agents platform resources** (`/v1/agents*`, `/v1/mcp-connections*`, `/v1/secrets*`, `/v1/skills*`): Accept `Authorization: Bearer` or `X-API-Key` and return the `AgentsError` envelope\n","version":"1.0.0","x-sandbase-session-contract":{"status":"active","feature":"Agents platform Sessions","description":"A Session (ses_*) runs one saved Agent version in a SandBase-hosted environment. Sessions are created directly with POST /v1/agents/sessions. Internal runtime identities are never exposed."},"contact":{"name":"SandBase","url":"https://www.sandbase.ai"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.sandbase.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Chat Completions","description":"OpenAI-compatible LLM Gateway"},{"name":"Responses","description":"OpenAI-compatible Responses API"},{"name":"Embeddings","description":"OpenAI-compatible text embeddings"},{"name":"Images","description":"OpenAI-compatible image generation and editing"},{"name":"Messages","description":"Anthropic-compatible Messages API"},{"name":"Gemini","description":"Google Gemini-compatible GenerateContent and Interactions APIs"},{"name":"Official Native API","description":"Provider-native model protocols, currently ByteDance Seedance content-generation tasks"},{"name":"Agents","description":"Saved, versioned Agent configurations and the public Agent catalog"},{"name":"Sessions","description":"Run an Agent version, send input, stream events, and read history"},{"name":"Models","description":"Model catalog"},{"name":"Tasks","description":"Asynchronous model task status, settlement, and usage"},{"name":"Webhooks","description":"Register organization webhooks for asynchronous model generation events"},{"name":"Account","description":"Organization balance and API execution history"},{"name":"Skills","description":"Versioned ZIP instruction bundles that Agents can mount"},{"name":"MCP Connections","description":"Remote HTTPS MCP servers that Agents can call"},{"name":"Secrets","description":"Write-only Bearer tokens for MCP connections"}],"paths":{"/v1/chat/completions":{"post":{"operationId":"createChatCompletion","tags":["Chat Completions"],"summary":"Create chat completion","description":"OpenAI-compatible chat completions endpoint. SandBase uses model and stream for routing and preserves additional provider-compatible fields when the selected route uses the same protocol. Support for provider-specific fields can vary when SandBase translates between protocols.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Chat completion response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}},"text/event-stream":{"schema":{"type":"string","description":"SSE stream of chat.completion.chunk events, followed by data: [DONE]."}}}},"400":{"description":"Invalid JSON, missing model, or an invalid provider request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"Organization spending limit reached","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionError"},{"$ref":"#/components/schemas/TaskCostError"}]}}}},"403":{"description":"Organization is disabled, or the API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionError"},{"$ref":"#/components/schemas/APIKeyScopeError"}]}}}},"404":{"description":"Model not found or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"500":{"description":"Request persistence or organization lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}},"502":{"description":"Invalid response from the selected provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}},"503":{"description":"No provider route succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}}}}},"/v1/responses":{"post":{"operationId":"createResponse","tags":["Responses"],"summary":"Create a model response","description":"OpenAI-compatible Responses API endpoint. SandBase validates model and stream for routing, rewrites model to the selected provider mapping, and preserves other request fields. Responses are rebuilt from public OpenAI fields: unknown provider, routing, account, and billing extensions are removed. Unsafe responses fail closed instead of being forwarded.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesRequest"}}}},"responses":{"200":{"description":"OpenAI-compatible response object or event stream from the selected provider.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Sanitized OpenAI Responses events. Public response.* and error events are forwarded; unknown private events and non-public event fields are removed. A malformed stream closes without forwarding unsafe data."}}}},"400":{"description":"Invalid JSON, missing model, no provider, or upstream request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}},"401":{"description":"Missing or invalid API key, or upstream authentication rejection","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TaskCostError"},{"$ref":"#/components/schemas/ChatCompletionError"}]}}}},"402":{"description":"Organization or API Key spending limit reached","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TaskCostError"},{"$ref":"#/components/schemas/ChatCompletionError"}]}}}},"403":{"description":"API key scope or upstream permission rejection","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TaskCostError"},{"$ref":"#/components/schemas/APIKeyScopeError"},{"$ref":"#/components/schemas/ChatCompletionError"}]}}}},"413":{"description":"Upstream provider rejected the request as too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}},"500":{"description":"Prediction lifecycle or organization lookup failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionError"},{"$ref":"#/components/schemas/TaskCostError"}]}}}},"502":{"description":"Upstream response could not be safely parsed and sanitized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}},"503":{"description":"Routing failed or every provider candidate was exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionError"}}}}}}},"/v1/embeddings":{"post":{"operationId":"createEmbedding","tags":["Embeddings"],"summary":"Create embeddings","description":"OpenAI-compatible embeddings endpoint for semantic search, RAG, clustering, and classification. SandBase validates the logical model and forwards provider-compatible embedding fields; model-specific constraints are defined by the selected model and upstream provider.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingRequest"}}}},"responses":{"200":{"description":"Embedding response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingResponse"}}}},"400":{"description":"Invalid request or non-embedding model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"Organization or API Key spending limit reached","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EmbeddingError"},{"$ref":"#/components/schemas/TaskCostError"}]}}}},"403":{"description":"Organization is disabled, or the API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EmbeddingError"},{"$ref":"#/components/schemas/APIKeyScopeError"}]}}}},"404":{"description":"Logical model not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingError"}}}},"500":{"description":"Request persistence or organization lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingError"}}}},"503":{"description":"No provider route succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingError"}}}}}}},"/v1/images/generations":{"post":{"operationId":"createImage","tags":["Images"],"summary":"Generate an image","description":"Generate images through the synchronous OpenAI Images-compatible endpoint. Supported public model names are gpt-image-2, gpt-image-2.5-flare, and gpt-image-2.5-sunburst. Additional compatible JSON fields are forwarded unchanged. Streaming and asynchronous mode are not supported on this endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationRequest"}}}},"responses":{"200":{"description":"Generated images and authoritative token usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagesResponse"}}}},"400":{"description":"Invalid body, unsupported model, streaming request, or provider request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIImagesError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"Organization or API Key spending limit reached","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/OpenAIImagesError"},{"$ref":"#/components/schemas/TaskCostError"}]}}}},"403":{"description":"Organization is disabled, or the API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TaskCostError"},{"$ref":"#/components/schemas/APIKeyScopeError"}]}}}},"404":{"description":"Routed image model is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIImagesError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"500":{"description":"Request persistence or response processing failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/OpenAIImagesError"},{"$ref":"#/components/schemas/TaskCostError"}]}}}},"502":{"description":"Provider returned an invalid native response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIImagesError"}}}},"503":{"description":"No provider route succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIImagesError"}}}}}}},"/v1/images/edits":{"post":{"operationId":"createImageEdit","tags":["Images"],"summary":"Edit an image","description":"Edit one or more uploaded images through the synchronous OpenAI Images-compatible multipart endpoint. Supported public model names are gpt-image-2, gpt-image-2.5-flare, and gpt-image-2.5-sunburst. Repeating the image field is supported. Additional compatible multipart fields are forwarded unchanged. Streaming and asynchronous mode are not supported on this endpoint.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImageEditRequest"}}}},"responses":{"200":{"description":"Edited images and authoritative token usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagesResponse"}}}},"400":{"description":"Invalid multipart body, unsupported model, streaming request, or provider request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIImagesError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"Organization or API Key spending limit reached","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/OpenAIImagesError"},{"$ref":"#/components/schemas/TaskCostError"}]}}}},"403":{"description":"Organization is disabled, or the API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TaskCostError"},{"$ref":"#/components/schemas/APIKeyScopeError"}]}}}},"404":{"description":"Routed image-edit model is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIImagesError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"500":{"description":"Request persistence or response processing failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/OpenAIImagesError"},{"$ref":"#/components/schemas/TaskCostError"}]}}}},"502":{"description":"Provider returned an invalid native response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIImagesError"}}}},"503":{"description":"No provider route succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIImagesError"}}}}}}},"/v1/messages":{"post":{"operationId":"createMessage","tags":["Messages"],"summary":"Create message (Anthropic compatible)","description":"Anthropic Messages-compatible endpoint. SandBase uses model and stream for routing, maps the public model name to the selected provider, and otherwise preserves the compatible request and response protocol. Provider compatibility rules may remove or reject unsupported beta fields before an upstream attempt.","security":[{"BearerAuth":[]},{"AnthropicApiKey":[]}],"parameters":[{"name":"anthropic-version","in":"header","required":false,"description":"Anthropic API version. Defaults to 2023-06-01 when omitted.","schema":{"type":"string","default":"2023-06-01","example":"2023-06-01"}},{"name":"anthropic-beta","in":"header","required":false,"description":"Comma-separated Anthropic beta feature identifiers. Availability is provider-specific.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","max_tokens","messages"],"additionalProperties":true,"description":"Anthropic-compatible request. Additional fields are preserved unless a selected provider's compatibility rules remove or reject them.","properties":{"model":{"type":"string","example":"claude-sonnet-5"},"max_tokens":{"type":"integer","example":4096},"messages":{"type":"array","items":{"type":"object","required":["role","content"],"additionalProperties":true,"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":true}}]}}}},"system":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":true}}]},"temperature":{"type":"number","minimum":0,"maximum":1},"top_p":{"type":"number","minimum":0,"maximum":1},"top_k":{"type":"integer","minimum":0},"stop_sequences":{"type":"array","items":{"type":"string"}},"stream":{"type":"boolean","default":false},"metadata":{"type":"object","additionalProperties":true},"tools":{"type":"array","items":{"type":"object","additionalProperties":true}},"tool_choice":{"type":"object","additionalProperties":true},"thinking":{"type":"object","description":"Extended thinking configuration when supported by the selected model.","additionalProperties":true}}}}}},"responses":{"200":{"description":"Anthropic message response or event stream from the selected provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicMessageResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Anthropic SSE events, including provider-defined beta events and possible in-stream error events."}}}},"400":{"description":"Invalid JSON, missing model, unsupported feature, or invalid provider request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"402":{"description":"Organization balance and credit are exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"403":{"description":"API Key spending limit reached, organization disabled, or upstream permission rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"404":{"description":"Model or upstream resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"413":{"description":"Provider rejected the request as too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"429":{"description":"Provider rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"500":{"description":"Prediction lifecycle or provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"502":{"description":"Upstream stream ended before usable content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}},"503":{"description":"Routing failed or all provider candidates were unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicError"}}}}}}},"/v1beta/models/{model}:generateContent":{"post":{"operationId":"generateGeminiContent","tags":["Gemini"],"summary":"Generate content with the Google Gemini protocol","description":"Accepts a Google Gemini GenerateContent request and returns a Gemini-compatible response. A bare model name,\nsuch as gemini-3.5-flash, is normalized to the SandBase catalog name google/gemini-3.5-flash. This endpoint\nalso accepts x-goog-api-key and the key query parameter for Google SDK compatibility, although headers are safer.\nModels with a native passthrough mapping preserve provider-defined request and response fields, including image\nresponse modalities. Other mappings may use the translated capability subset documented in the schema below.\n","security":[{"GoogleApiKey":[]},{"BearerAuth":[]},{"GoogleQueryApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/GeminiModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiGenerateContentRequest"}}}},"responses":{"200":{"description":"Gemini GenerateContent response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiGenerateContentResponse"}}}},"400":{"description":"Invalid JSON or a request rejected by the selected native or translated mapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"402":{"description":"Organization balance and credit are exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"403":{"description":"API Key spending limit reached, organization disabled, or upstream permission rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"404":{"description":"Model, method, or upstream resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"429":{"description":"Provider rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"500":{"description":"Prediction lifecycle or provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"502":{"description":"Upstream response failed or could not be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"503":{"description":"Routing failed or all provider candidates were unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"504":{"description":"Upstream request timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}}}}},"/v1beta/models/{model}:streamGenerateContent":{"post":{"operationId":"streamGeminiContent","tags":["Gemini"],"summary":"Stream content with the Google Gemini protocol","description":"Returns a streamed JSON array by default. Add alt=sse to receive Server-Sent Events instead.","security":[{"GoogleApiKey":[]},{"BearerAuth":[]},{"GoogleQueryApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/GeminiModel"},{"name":"alt","in":"query","schema":{"type":"string","enum":["sse"]},"description":"Set to sse for Server-Sent Events. Any other or omitted value uses the Google-compatible streamed JSON array."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiGenerateContentRequest"}}}},"responses":{"200":{"description":"Gemini response frames","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GeminiGenerateContentResponse"}}},"text/event-stream":{"schema":{"type":"string","description":"SSE data frames containing Gemini GenerateContentResponse objects."}}}},"400":{"description":"Invalid JSON or an input field that SandBase cannot safely translate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"402":{"description":"Organization balance and credit are exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"403":{"description":"API Key spending limit reached, organization disabled, or upstream permission rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"404":{"description":"Model, method, or upstream resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"429":{"description":"Provider rate limit exceeded before streaming starts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"500":{"description":"Prediction lifecycle or provider error before streaming starts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"502":{"description":"Upstream stream could not be translated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"503":{"description":"Routing failed or all provider candidates were unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"504":{"description":"Upstream request timed out before streaming starts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}}}}},"/v1beta/interactions":{"post":{"operationId":"createGeminiInteraction","tags":["Gemini"],"summary":"Create a Google Gemini Interaction","description":"Proxies the Google Interactions protocol while routing the logical model through SandBase. Successful requests\nalways return HTTP 200. Check status: an in_progress response is pollable and is not a completed result.\nSet stream=true for SSE, or background=true for a durable background submission; they cannot both be true.\n","security":[{"GoogleApiKey":[]},{"BearerAuth":[]},{"GoogleQueryApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiInteractionRequest"}}}},"responses":{"200":{"description":"Current or terminal Interaction, or an Interaction event stream","headers":{"Location":{"schema":{"type":"string"},"description":"Polling path when the returned Interaction is still in_progress. This convenience header may be omitted for a terminal response."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiInteraction"}},"text/event-stream":{"schema":{"type":"string","description":"Google Interactions SSE events ending with a done event and data [DONE]. In-stream failures use an error event after headers are written."}}}},"400":{"description":"Invalid JSON, missing model, unsupported Agent interaction, incompatible background and stream settings, stale conversation affinity, or upstream request rejection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"402":{"description":"Organization balance and credit are exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"403":{"description":"API Key spending limit reached, organization disabled, or upstream permission rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"404":{"description":"Logical model or usable provider was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"422":{"description":"Upstream rejected otherwise valid Interaction fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"429":{"description":"Provider rate limit exceeded after failover attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"500":{"description":"Prediction lifecycle or internal persistence failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"502":{"description":"Upstream response exceeded the gateway size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"503":{"description":"Routing, upstream connection, or durable background handoff failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"504":{"description":"Upstream request timed out after failover attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}}}}},"/v1beta/interactions/{id}":{"get":{"operationId":"getGeminiInteraction","tags":["Gemini"],"summary":"Get a Google Gemini Interaction","description":"Retrieves the Interaction created by the same SandBase API key. Non-terminal responses omit partial output and\nusage. When upstream media has expired, a terminal fallback can preserve structure and metadata without the\noriginal media bytes; download terminal media promptly rather than treating this endpoint as durable storage.\n","security":[{"GoogleApiKey":[]},{"BearerAuth":[]},{"GoogleQueryApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Upstream Interaction ID returned by POST. It is not a SandBase prediction ID."}],"responses":{"200":{"description":"Current or terminal Interaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiInteraction"}}}},"400":{"description":"Empty Interaction ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"402":{"description":"Organization balance and credit are exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"403":{"description":"API Key spending limit reached or organization disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"404":{"description":"Interaction is unknown, expired, or not owned by the current API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"500":{"description":"Organization admission lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"502":{"description":"Upstream Interaction response exceeded the gateway size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}},"503":{"description":"Affinity storage, provider lookup, credentials, or upstream retrieval is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiError"}}}}}}},"/api/v3/contents/generations/tasks":{"post":{"operationId":"createVolcengineContentsGenerationTask","tags":["Official Native API"],"summary":"Create a content generation task","description":"Creates an asynchronous Seedance video generation task using the Volcengine Ark native request shape.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineContentsGenerationRequest"}}}},"responses":{"200":{"description":"Task accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineTaskCreated"}}}},"400":{"description":"Invalid JSON, unsupported model or content mode, or rejected generation parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"402":{"description":"Organization balance and credit are exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"403":{"description":"API Key spending limit reached, organization disabled, or upstream permission rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"404":{"description":"Model or upstream resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"429":{"description":"Provider rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"500":{"description":"Prediction lifecycle or provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}}}}},"/api/v3/contents/generations/tasks/{task_id}":{"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Task ID returned by the create operation."}],"get":{"operationId":"getVolcengineContentsGenerationTask","tags":["Official Native API"],"summary":"Get a content generation task","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Current task state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineTask"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"402":{"description":"Organization balance and credit are exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"403":{"description":"API Key spending limit reached or organization disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"404":{"description":"Task is unknown, deleted, not native, or not owned by the current API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}},"500":{"description":"Task lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolcengineError"}}}}}}},"/events/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhooks","description":"Lists the organization's webhooks. signatureSecret is never returned.","security":[{"BearerAuth":[]},{"WebhookApiKey":[]}],"responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}},"500":{"description":"Webhook lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Create a webhook","description":"Registers a webhook for asynchronous model generation events. The response is the only time signatureSecret is returned.","security":[{"BearerAuth":[]},{"WebhookApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateRequest"}}}},"responses":{"200":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"}}}},"400":{"description":"Invalid body, URL, resourceType, or events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}},"500":{"description":"Webhook creation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}}}}},"/events/webhooks/{webhook_id}":{"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID returned by create or list."}],"patch":{"operationId":"updateWebhook","tags":["Webhooks"],"summary":"Update a webhook","description":"Updates the fields sent; omitted fields remain unchanged. The resulting resourceType and events subscription must be valid. signatureSecret cannot be changed.","security":[{"BearerAuth":[]},{"WebhookApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdateRequest"}}}},"responses":{"200":{"description":"Updated webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"Invalid body or subscription, or the request includes signatureSecret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}},"404":{"description":"webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}},"500":{"description":"Webhook update failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}}}},"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Delete a webhook","security":[{"BearerAuth":[]},{"WebhookApiKey":[]}],"responses":{"204":{"description":"Webhook deleted"},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}},"404":{"description":"webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}},"500":{"description":"Webhook deletion failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookError"}}}}}}},"/v1/account/balance":{"get":{"operationId":"getAccountBalance","tags":["Account"],"summary":"Get account balance","description":"Returns the balance and optional credit settings for the organization that owns the API key.","responses":{"200":{"description":"Organization balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountBalance"}}}},"401":{"description":"The API key did not resolve an organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"API key spending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/account/history":{"get":{"operationId":"listAccountHistory","tags":["Account"],"summary":"List execution history","description":"Lists recent execution records for the API key's organization, newest first. Input and output snapshots are included only when stored JSON can be decoded. Error messages are sanitized before they are returned.","parameters":[{"name":"model","in":"query","schema":{"type":"string"},"description":"Exact logical model name."},{"name":"api_key_id","in":"query","schema":{"type":"string"},"description":"Exact API Key resource ID within the organization."},{"name":"type","in":"query","schema":{"type":"string"},"description":"Execution category. Supported filters are multimodal (image, video, and audio), llm, and api; any other value applies no type filter."},{"name":"status","in":"query","schema":{"type":"string","enum":["completed","failure","in_progress"]},"description":"Status group. failure includes failed and timeout; in_progress includes pending and running."},{"name":"error_type","in":"query","schema":{"type":"string","maxLength":50},"description":"Exact error type. Use unknown for records without an error type."},{"name":"range","in":"query","schema":{"type":"string","default":"7d"},"description":"Rolling created-at range when an explicit analytics window is not used. Supported values are 1h, 24h, 7d, and 30d; every other value falls back to 7d."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"request_id","in":"query","schema":{"type":"string","maxLength":64},"description":"Exact organization-scoped execution ID lookup. When set, other filters are ignored and the response is forced to page 1 with page_size 1."},{"name":"time_basis","in":"query","schema":{"type":"string","enum":["created_at","settled_at"],"default":"created_at"},"description":"Timestamp basis for an explicit start_at/end_at window."},{"name":"billing_scope","in":"query","schema":{"type":"string","enum":["any","positive","token"],"default":"any"},"description":"Settlement filter. positive and token are valid only with time_basis=settled_at."},{"name":"start_at","in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive RFC 3339 window start. Must be paired with end_at; the window cannot exceed 32 days."},{"name":"end_at","in":"query","schema":{"type":"string","format":"date-time"},"description":"Exclusive RFC 3339 window end. Must be paired with start_at."},{"name":"latency_sample","in":"query","schema":{"type":"string","enum":["positive","terminal_positive"]},"description":"Restrict latency samples to positive values, optionally only for terminal executions."},{"name":"min_latency_ms","in":"query","schema":{"type":"integer","minimum":0},"description":"Minimum recorded latency in milliseconds."},{"name":"timezone","in":"query","schema":{"type":"string","maxLength":64},"description":"Compatibility parameter. Without request_id, a valid IANA time-zone name is required when supplied, but raw response timestamps remain unchanged. Exact request_id mode ignores it."}],"responses":{"200":{"description":"Paginated execution history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountHistoryPage"}}}},"400":{"description":"Invalid filter or analytics window","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"401":{"description":"The API key did not resolve an organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"API key spending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"500":{"description":"History lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/tasks/{task_id}/cost":{"get":{"operationId":"getTaskCost","tags":["Tasks"],"summary":"Get task cost and usage","description":"Returns the settlement status, final user cost, estimated cost, and token usage for a recent task.\nPublic API keys can retrieve only tasks originally created by that same API key, even when another key belongs to the same organization.\nThis lookup remains available after the key reaches its spending limit, but expired, revoked, or scoped keys are still rejected.\nWhen `settled` is false, `cost` is not final and must not be used for billing or reconciliation.\nUse `estimated_cost` only as a display estimate until final settlement completes.\nOlder task execution records may be archived after the retention window and then return 404.\nUse billing records or billing exports for long-term reconciliation.\n","parameters":[{"name":"task_id","in":"path","required":true,"description":"Opaque task ID returned by a billable operation, including an x-task-id response header when present.","schema":{"type":"string"}}],"responses":{"200":{"description":"Task cost and usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"404":{"description":"Task does not exist or is not accessible with the current API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/run":{"post":{"operationId":"runCapability","tags":["Models"],"summary":"Run a model or API capability","description":"Executes the selected catalog capability. Capability-specific fields must match the live schema returned by\nthe model detail endpoint or Store. Asynchronous capabilities can be polled with GET /v1/run/{id}.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}}},"responses":{"200":{"description":"Capability completed synchronously, or a streaming response started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events when stream is true or mode is stream and the selected model supports streaming."}}}},"202":{"description":"Capability accepted for asynchronous execution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}}}},"400":{"description":"Invalid JSON, unsupported execution mode, invalid capability input, or invalid webhook URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"Insufficient balance or spending limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"The current API key cannot use the selected capability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"404":{"description":"Model or capability not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"500":{"description":"Internal execution error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"502":{"description":"Upstream provider returned an invalid response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"503":{"description":"No provider is currently available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/run/{id}":{"get":{"operationId":"getRun","tags":["Models"],"summary":"Get an asynchronous run","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque ID returned by POST /v1/run. Do not assume a prefix or derive it independently."}],"responses":{"200":{"description":"Current or terminal run state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"API key spending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/api/{vendor}/{upstream_path}":{"parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"First segment of the enabled catalog capability name."},{"name":"upstream_path","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Remaining capability-name path. It may contain multiple literal slash-separated segments; do not percent-encode those slashes."}],"get":{"operationId":"getAPICapability","tags":["Models"],"summary":"Invoke a catalog API capability with GET","description":"Resolves the enabled catalog model named vendor/upstream_path and executes it through the unified pipeline. The request body is empty; capability-specific query parameters remain on the incoming request and are available only when supported by that capability.","responses":{"200":{"description":"Capability-specific synchronous response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughResponse"}}}},"202":{"description":"Capability accepted for asynchronous execution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughResponse"}}}},"400":{"description":"Capability input is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"Insufficient balance or spending limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key or capability access is forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"404":{"description":"No enabled catalog capability matches the vendor and path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"500":{"description":"Internal execution error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"502":{"description":"Upstream provider returned an invalid response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"503":{"description":"No provider is currently available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}}}},"post":{"operationId":"postAPICapability","tags":["Models"],"summary":"Invoke a catalog API capability with POST","description":"Resolves the enabled catalog model named vendor/upstream_path and executes a JSON object through the unified pipeline. When model is omitted, the URL-derived capability name is injected. A supplied model field is preserved and remains authoritative.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Capability-specific synchronous response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughResponse"}}}},"202":{"description":"Capability accepted for asynchronous execution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughResponse"}}}},"400":{"description":"Body is not a JSON object or capability input is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"Insufficient balance or spending limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key or capability access is forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"404":{"description":"No enabled catalog capability matches the vendor and path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"500":{"description":"Internal execution error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"502":{"description":"Upstream provider returned an invalid response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}},"503":{"description":"No provider is currently available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIPassthroughError"}}}}}}},"/v1/upload":{"post":{"operationId":"uploadMedia","tags":["Models"],"summary":"Upload media for model input","description":"Uploads one image, audio, or video file and returns its stored URL. The server detects the actual MIME type\nfrom the file bytes and filename; the optional type form field is only a hint and does not override detection.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadMediaRequest"}}}},"responses":{"200":{"description":"Media uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadMediaResponse"}}}},"400":{"description":"Missing file, invalid multipart data, unsupported MIME type, or file too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"API key spending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"500":{"description":"File could not be read or stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"503":{"description":"File storage is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/assets":{"post":{"operationId":"createAsset","tags":["Models"],"summary":"Register a media asset","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetRequest"}}}},"responses":{"200":{"description":"Asset registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetResponse"}}}},"400":{"description":"Invalid JSON, missing URL, or unsupported asset type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"API key spending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"500":{"description":"Asset provider credentials are unavailable or the asset record could not be saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"502":{"description":"Upstream asset registration failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/assets/{id}":{"get":{"operationId":"getAsset","tags":["Models"],"summary":"Get asset metadata and a signed download URL","parameters":[{"name":"id","in":"path","required":true,"description":"External Asset ID without the asset:// prefix.","schema":{"type":"string"}}],"responses":{"200":{"description":"Asset metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAssetResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"API key spending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"404":{"description":"Asset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"500":{"description":"Internal asset lookup error or provider credentials are unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"502":{"description":"Upstream asset query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/models":{"get":{"operationId":"listModels","tags":["Models"],"summary":"List models","description":"List enabled logical models in the OpenAI-compatible model-list shape. Use the detail endpoint for capabilities, schemas, and pricing.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Fuzzy search over model name, display name, vendor, and description."},{"name":"vendor","in":"query","schema":{"type":"string"},"description":"Exact, case-sensitive vendor filter."},{"name":"type","in":"query","schema":{"type":"string","default":"llm"},"description":"Filter by model type. Omission defaults to llm; an explicitly empty value removes the type filter."},{"name":"order","in":"query","schema":{"type":"string","enum":["sort_order","most-popular","newest","name"],"default":"sort_order"},"description":"Sort order."}],"responses":{"200":{"description":"Model list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelListResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"API key spending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"500":{"description":"Model catalog lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/models/{id_or_name}":{"get":{"operationId":"getModel","tags":["Models"],"summary":"Get model details","description":"Get model details by UUID or full logical model name. Model names containing slashes are supported as path segments, for example /v1/models/openai/gpt-5.6-luna. Name lookup returns enabled catalog models; UUID lookup can return a disabled catalog record with enabled set to false. Protocol-ingress-only models are never returned.","parameters":[{"name":"id_or_name","in":"path","required":true,"schema":{"type":"string"},"description":"Model ID or full model name."}],"responses":{"200":{"description":"Model details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelDetail"}}}},"400":{"description":"Missing model ID or name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"402":{"description":"API key spending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}},"403":{"description":"API key scope does not authorize this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyScopeError"}}}},"404":{"description":"Model not found or not publicly discoverable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCostError"}}}}}}},"/v1/agents":{"post":{"operationId":"createAgent","tags":["Agents"],"summary":"Create agent","description":"Create a saved, versioned Agent (version 1). The request is strict JSON (1 MiB maximum; unknown fields are rejected). Idempotency-Key is optional; the service generates one when omitted, so send your own key when you retry.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/OpenAIBeta"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateRequest"}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"get":{"operationId":"listAgents","tags":["Agents"],"summary":"List agents","description":"List Agents owned by the API key organization with cursor pagination.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/AgentStatusFilter"},{"$ref":"#/components/parameters/AgentsLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"},{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"Agent page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/catalog":{"get":{"operationId":"listAgentCatalog","tags":["Agents"],"summary":"List public agent catalog","description":"List public Agents published to the SandBase catalog. Catalog entries are read-only; clone one to customize it.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/AgentsLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"}],"responses":{"200":{"description":"Catalog page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCatalogList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/catalog/{agent_id}":{"parameters":[{"$ref":"#/components/parameters/AgentIdPath"}],"get":{"operationId":"getAgentCatalogEntry","tags":["Agents"],"summary":"Get public catalog agent","description":"Read one public catalog Agent, optionally at a specific version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"name":"version","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Catalog version. Defaults to the current public version."}],"responses":{"200":{"description":"Catalog Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCatalogEntry"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/catalog/{agent_id}/clone":{"parameters":[{"$ref":"#/components/parameters/AgentIdPath"}],"post":{"operationId":"cloneAgentCatalogEntry","tags":["Agents"],"summary":"Clone public catalog agent","description":"Copy a public catalog Agent into your organization as a new private Agent.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCloneRequest"}}}},"responses":{"201":{"description":"Private Agent created from the catalog entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/{agent_id}":{"parameters":[{"$ref":"#/components/parameters/AgentIdPath"}],"get":{"operationId":"getAgent","tags":["Agents"],"summary":"Get agent","description":"Read an Agent, including archived Agents.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"post":{"operationId":"updateAgent","tags":["Agents"],"summary":"Update agent","description":"OpenAI SDK-style partial update. Only the listed fields are accepted; supplied fields replace the saved values and create a new version. No row_version is needed. Archived Agents return 404.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/OpenAIBeta"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUpdateRequest"}}}},"responses":{"200":{"description":"Updated Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"patch":{"operationId":"replaceAgent","tags":["Agents"],"summary":"Update agent with row_version","description":"Product compare-and-set update. row_version is required and must match the current value. Explicit null values are rejected. A successful write creates a new version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentReplaceRequest"}}}},"responses":{"200":{"description":"Updated Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"delete":{"operationId":"deleteAgent","tags":["Agents"],"summary":"Delete agent","description":"Archives the Agent. Agents are never hard-deleted; use unarchive to restore access.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"Agent archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDeleted"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/{agent_id}/archive":{"parameters":[{"$ref":"#/components/parameters/AgentIdPath"}],"post":{"operationId":"archiveAgent","tags":["Agents"],"summary":"Archive agent","description":"Archive an Agent. row_version must match the current value.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRowVersionRequest"}}}},"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/{agent_id}/unarchive":{"parameters":[{"$ref":"#/components/parameters/AgentIdPath"}],"post":{"operationId":"unarchiveAgent","tags":["Agents"],"summary":"Unarchive agent","description":"Return an archived Agent to active. row_version must match the current value.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRowVersionRequest"}}}},"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/{agent_id}/restore":{"parameters":[{"$ref":"#/components/parameters/AgentIdPath"}],"post":{"operationId":"restoreAgentVersion","tags":["Agents"],"summary":"Restore agent version","description":"Create a new current version from the configuration of an earlier version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRestoreRequest"}}}},"responses":{"200":{"description":"Agent with the restored configuration as a new version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/{agent_id}/versions":{"parameters":[{"$ref":"#/components/parameters/AgentIdPath"}],"get":{"operationId":"listAgentVersions","tags":["Agents"],"summary":"List agent versions","description":"List immutable version snapshots with offset pagination.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OffsetLimit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Version page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/{agent_id}/versions/{version}":{"parameters":[{"$ref":"#/components/parameters/AgentIdPath"},{"$ref":"#/components/parameters/AgentVersionPath"}],"get":{"operationId":"getAgentVersion","tags":["Agents"],"summary":"Get agent version","description":"Read one immutable version snapshot. version must be a positive integer.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Version snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersion"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions":{"post":{"operationId":"createSession","tags":["Sessions"],"summary":"Create session","description":"Create a Session for a saved Agent, or for an inline Agent defined in the request. The Agent configuration, Skills, and MCP connections are frozen for the lifetime of the Session. With stream=true and an initial input, the 201 response is a Server-Sent Events stream of the first turn instead of a JSON Session. Execution admission (balance and organization status) is checked here.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/OpenAIBeta"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreateRequest"}}}},"responses":{"201":{"description":"Session created. With stream=true, a text/event-stream of the first turn whose first event, agent.session.created, carries the Session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}},"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events in the Stream events format: an event line with the event type and a data line with its JSON payload."}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, an unsupported option, or stream=true without input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: the Agent is archived or not ready, an MCP connection or Secret is not active, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"get":{"operationId":"listSessions","tags":["Sessions"],"summary":"List sessions","description":"List Sessions with cursor pagination.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/SessionLifecycleFilter"},{"name":"agent_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only return Sessions of this Agent."},{"$ref":"#/components/parameters/AgentsLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"},{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"Session page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"get":{"operationId":"getSession","tags":["Sessions"],"summary":"Get session","description":"Read a Session. Execution status is read live from the execution layer.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"Session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"post":{"operationId":"updateSession","tags":["Sessions"],"summary":"Update session metadata","description":"Replace the Session metadata map. metadata is the only accepted field. Archived Sessions return 404.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OpenAIBeta"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionUpdateRequest"}}}},"responses":{"200":{"description":"Session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"patch":{"operationId":"renameSession","tags":["Sessions"],"summary":"Rename session","description":"Change the Session title with compare-and-set on row_version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionRenameRequest"}}}},"responses":{"200":{"description":"Session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"delete":{"operationId":"deleteSession","tags":["Sessions"],"summary":"Delete session","description":"Archives the Session. Sessions are not hard-deleted.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"Session archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDeleted"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/events":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"post":{"operationId":"sendSessionEvents","tags":["Sessions"],"summary":"Send session input","description":"Send exactly one event: agent.session.input.message or agent.session.input.cancel. The SandBase extension form {input, file_ids} sends text with ready attachments and cannot be combined with events. Idempotency-Key is optional but recommended; reuse the same key when retrying the same input.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/OpenAIBeta"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionEventsRequest"}}}},"responses":{"202":{"description":"Input accepted. The response has no body.","x-sandbase-empty-body":true},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict (Session archived or attachment not ready), session_input_pending, session_input_expired, or session_environment_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"get":{"operationId":"streamSessionEvents","tags":["Sessions"],"summary":"Stream session events","description":"Open the live server-sent event stream. The stream is live-only: Last-Event-ID or after returns 400; read history with items or turns. The server writes a \": connected\" comment first.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"Server-sent events whose type starts with agent.session.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/events/stream":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"get":{"operationId":"streamSessionSnapshot","tags":["Sessions"],"summary":"Stream session snapshot and events","description":"SandBase product stream. Emits session.snapshot first, then live events and heartbeat. If the upstream stream breaks, the server emits stream.interrupted; call reconnect. cursor or Last-Event-ID returns 400.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"session.snapshot, live Session events, heartbeat, and stream.interrupted","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/items":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"get":{"operationId":"listSessionItems","tags":["Sessions"],"summary":"List session items","description":"Read Session items history with cursor pagination.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/AgentsLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"},{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"items page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsCursorList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/turns":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"get":{"operationId":"listSessionTurns","tags":["Sessions"],"summary":"List session turns","description":"Read Session turns history with cursor pagination.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/AgentsLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"},{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"turns page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsCursorList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/turns/{turn_id}":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"},{"$ref":"#/components/parameters/TurnIdPath"}],"get":{"operationId":"getSessionTurn","tags":["Sessions"],"summary":"Get session turn","description":"Read one Turn of the Session.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OpenAIBeta"}],"responses":{"200":{"description":"Turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionTurn"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/cancel":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"post":{"operationId":"cancelSession","tags":["Sessions"],"summary":"Cancel session turn","description":"Request cancellation of the in-progress Turn. The body may be empty or {}. Idempotency-Key is required. An idle Session also returns 202 with accepted true and nothing changes.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"}}}},"responses":{"202":{"description":"Cancellation accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCancelAccepted"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/archive":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"post":{"operationId":"archiveSession","tags":["Sessions"],"summary":"Archive session","description":"Archive session with compare-and-set on row_version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionRowVersionRequest"}}}},"responses":{"200":{"description":"Session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/unarchive":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"post":{"operationId":"unarchiveSession","tags":["Sessions"],"summary":"Unarchive session","description":"Unarchive session with compare-and-set on row_version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionRowVersionRequest"}}}},"responses":{"200":{"description":"Session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/reconnect":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"post":{"operationId":"reconnectSession","tags":["Sessions"],"summary":"Reconnect session","description":"Return the current Session and the product stream URL to reopen. Uses the agents.read scope.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Reconnect instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionReconnect"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/files":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"post":{"operationId":"uploadSessionFile","tags":["Sessions"],"summary":"Upload session file","description":"Upload one attachment (multipart field file, maximum 5 MiB) into the Session workspace. Idempotency-Key is required. Supported extensions: .txt, .md, .csv, .log, .json, .pdf, .png, .jpg, .jpeg, .webp. A failed transfer still returns 201 with status failed.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SessionFileUpload"}}}},"responses":{"201":{"description":"Attachment record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionFile"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"get":{"operationId":"listSessionFiles","tags":["Sessions"],"summary":"List session files","description":"List attachments with offset pagination (limit 1-100).","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OffsetLimit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Attachment page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionFileList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/files/{file_id}":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"},{"$ref":"#/components/parameters/FileIdPath"}],"delete":{"operationId":"deleteSessionFile","tags":["Sessions"],"summary":"Delete session file","description":"Delete an attachment. Pending uploads and archived Sessions return 409.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Attachment deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionFileDeleted"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/files/{file_id}/content":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"},{"$ref":"#/components/parameters/FileIdPath"}],"get":{"operationId":"downloadSessionFile","tags":["Sessions"],"summary":"Download session file","description":"Download the original bytes of a ready attachment.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Attachment bytes with the stored MIME type","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/workspace-files":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"get":{"operationId":"listSessionWorkspaceFiles","tags":["Sessions"],"summary":"List workspace files","description":"Read immediate file metadata under a normalized /workspace path. This is a read-only directory listing, not an attachment or artifact download. Use next as page with the same path, order and limit; restart from the first page if the cursor expires.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"name":"path","in":"query","required":false,"description":"Normalized absolute directory path under /workspace. No traversal, backslashes, or trailing slash.","schema":{"type":"string","maxLength":4096,"default":"/workspace"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"order","in":"query","required":false,"description":"Sort by path.","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},{"name":"page","in":"query","required":false,"description":"Opaque next cursor; omit for the first page.","schema":{"type":"string","minLength":1,"maxLength":1024}}],"responses":{"200":{"description":"List workspace files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionWorkspacePage"}}}},"400":{"description":"invalid_request or workspace_cursor_invalid; restart pagination for an invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: resource not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"workspace_provisioning or workspace_environment_missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"workspace_unavailable, authorization_unavailable, or storage_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/artifacts":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"}],"get":{"operationId":"listSessionArtifacts","tags":["Sessions"],"summary":"List session artifacts","description":"List immutable outputs captured under /workspace/outputs/. Use returned opaque artifact IDs for after and downloads; do not construct IDs from paths.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"order","in":"query","required":false,"description":"Artifact order.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"after","in":"query","required":false,"description":"Artifact ID from the preceding page; use last_id when has_more is true.","schema":{"type":"string"}}],"responses":{"200":{"description":"List session artifacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionArtifactList"}}}},"400":{"description":"invalid_request: invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: resource not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"executor_unavailable, authorization_unavailable, or storage_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/agents/sessions/{session_id}/artifacts/{artifact_id}/content":{"parameters":[{"$ref":"#/components/parameters/SessionIdPath"},{"name":"artifact_id","in":"path","required":true,"description":"Opaque art_ ID returned by the artifact list for this Session.","schema":{"type":"string"}}],"get":{"operationId":"downloadSessionArtifact","tags":["Sessions"],"summary":"Download session artifact","description":"Download a complete immutable artifact, up to 200 MiB. No query parameters. Range is unsupported and returns 416 after access checks. Content-Type follows the file extension, with application/octet-stream as fallback.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Complete artifact bytes; Content-Disposition is attachment and Cache-Control is no-store.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"invalid_request: invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: resource not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"416":{"description":"invalid_request: Range downloads are unsupported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"executor_unavailable, authorization_unavailable, or storage_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/mcp-connections":{"post":{"operationId":"createMCPConnection","tags":["MCP Connections"],"summary":"Create MCP connection","description":"Register a remote HTTPS MCP server, optionally authenticated with an active Secret whose server_url matches exactly. Idempotency-Key is required.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPConnectionCreateRequest"}}}},"responses":{"201":{"description":"Connection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPConnection"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"get":{"operationId":"listMCPConnections","tags":["MCP Connections"],"summary":"List MCP connections","description":"List connections with offset pagination.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OffsetLimit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Connection page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPConnectionList"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/mcp-connections/{connection_id}":{"parameters":[{"$ref":"#/components/parameters/MCPConnectionIdPath"}],"get":{"operationId":"getMCPConnection","tags":["MCP Connections"],"summary":"Get MCP connection","description":"Read a connection.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPConnection"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"put":{"operationId":"replaceMCPConnection","tags":["MCP Connections"],"summary":"Replace MCP connection","description":"Replace name, server_url, and secret_id with compare-and-set on row_version. Omitting secret_id makes the connection anonymous. A disabled connection stays disabled. Idempotency-Key is required.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPConnectionReplaceRequest"}}}},"responses":{"200":{"description":"Connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPConnection"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"delete":{"operationId":"deleteMCPConnection","tags":["MCP Connections"],"summary":"Disable MCP connection","description":"Disable the connection. Idempotency-Key is required. New Sessions cannot use it and existing Sessions that froze it reject further input.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"responses":{"204":{"description":"Connection disabled"},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/mcp-connections/{connection_id}/enable":{"parameters":[{"$ref":"#/components/parameters/MCPConnectionIdPath"}],"post":{"operationId":"enableMCPConnection","tags":["MCP Connections"],"summary":"Enable MCP connection","description":"Re-enable a disabled connection with compare-and-set on row_version. Idempotency-Key is required. A revoked Secret is never restored.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowVersionRequest"}}}},"responses":{"200":{"description":"Connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPConnection"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/secrets":{"post":{"operationId":"createSecret","tags":["Secrets"],"summary":"Create secret","description":"Store a write-only Bearer token for one MCP server URL. Idempotency-Key is required. The token is never returned.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretCreateRequest"}}}},"responses":{"201":{"description":"Secret created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Secret"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"get":{"operationId":"listSecrets","tags":["Secrets"],"summary":"List secrets","description":"List Secret metadata with offset pagination.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/OffsetLimit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Secret page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretList"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/secrets/{secret_id}":{"parameters":[{"$ref":"#/components/parameters/SecretIdPath"}],"get":{"operationId":"getSecret","tags":["Secrets"],"summary":"Get secret","description":"Read Secret metadata. The token is never returned.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Secret"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"delete":{"operationId":"deleteSecret","tags":["Secrets"],"summary":"Revoke secret","description":"Revoke the Secret. Idempotency-Key is required. Connections that use it stop working for new Sessions and further input.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"responses":{"204":{"description":"Secret revoked"},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/secrets/{secret_id}/rotate":{"parameters":[{"$ref":"#/components/parameters/SecretIdPath"}],"post":{"operationId":"rotateSecret","tags":["Secrets"],"summary":"Rotate secret","description":"Replace the token for the same server_url with compare-and-set on row_version. Idempotency-Key is required. Only new Sessions use the new token.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretRotateRequest"}}}},"responses":{"201":{"description":"Secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Secret"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills":{"post":{"operationId":"createSkill","tags":["Skills"],"summary":"Create skill","description":"Upload a ZIP bundle (one files part, maximum 5 MiB) containing a SKILL.md with name and description frontmatter. Creates version 1. Idempotency-Key is optional.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SkillUploadForm"}}}},"responses":{"201":{"description":"Skill created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"get":{"operationId":"listSkills","tags":["Skills"],"summary":"List skills","description":"List organization Skills with cursor pagination (limit 0-100).","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/SkillLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"}],"responses":{"200":{"description":"Skill page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/catalog":{"get":{"operationId":"listSkillCatalog","tags":["Skills"],"summary":"List public skill catalog","description":"List public Skills.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/SkillLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"}],"responses":{"200":{"description":"Skill page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/catalog/{skill_id}":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"}],"get":{"operationId":"getSkillCatalogEntry","tags":["Skills"],"summary":"Get public skill","description":"Read one public Skill.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/catalog/{skill_id}/versions":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"}],"get":{"operationId":"listSkillCatalogVersions","tags":["Skills"],"summary":"List public skill versions","description":"List versions of a public Skill.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/SkillLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"}],"responses":{"200":{"description":"Version page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillVersionList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/catalog/{skill_id}/versions/{version}":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"},{"$ref":"#/components/parameters/SkillVersionPath"}],"get":{"operationId":"getSkillCatalogVersion","tags":["Skills"],"summary":"Get public skill version","description":"Read one version of a public Skill.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillVersion"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/catalog/{skill_id}/versions/{version}/content":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"},{"$ref":"#/components/parameters/SkillVersionPath"}],"get":{"operationId":"downloadSkillCatalogVersion","tags":["Skills"],"summary":"Download public skill version","description":"Download the ZIP bundle of a public Skill version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Skill ZIP bundle","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/{skill_id}":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"}],"get":{"operationId":"getSkill","tags":["Skills"],"summary":"Get skill","description":"Read a Skill.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"post":{"operationId":"updateSkill","tags":["Skills"],"summary":"Update skill","description":"Change default_version, status, or metadata. row_version is required when metadata is supplied; otherwise the current value is used.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillUpdateRequest"}}}},"responses":{"200":{"description":"Skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"delete":{"operationId":"deleteSkill","tags":["Skills"],"summary":"Delete skill","description":"Delete a Skill. A Skill referenced by any Agent version returns 409.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Skill deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillDeleted"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/{skill_id}/content":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"}],"get":{"operationId":"downloadSkill","tags":["Skills"],"summary":"Download skill","description":"Download the ZIP bundle of the default version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Skill ZIP bundle","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/{skill_id}/versions":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"}],"get":{"operationId":"listSkillVersions","tags":["Skills"],"summary":"List skill versions","description":"List Skill versions with cursor pagination (limit 0-100).","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/SkillLimit"},{"$ref":"#/components/parameters/AgentsAfter"},{"$ref":"#/components/parameters/AgentsOrder"}],"responses":{"200":{"description":"Version page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillVersionList"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}},"post":{"operationId":"createSkillVersion","tags":["Skills"],"summary":"Upload skill version","description":"Upload a new ZIP bundle as the next version. Set default=true to make it the default version. Idempotency-Key is optional.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SkillVersionUploadForm"}}}},"responses":{"200":{"description":"Version created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillVersion"}}}},"400":{"description":"invalid_request (malformed JSON, unknown fields, failed validation, or an unsupported option)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"409":{"description":"conflict: stale row_version, lifecycle state, or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"502":{"description":"executor_rejected or executor_contract_error from the execution layer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/{skill_id}/versions/{version}":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"},{"$ref":"#/components/parameters/SkillVersionPath"}],"get":{"operationId":"getSkillVersion","tags":["Skills"],"summary":"Get skill version","description":"Read one Skill version. Version identifiers are strings.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillVersion"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}},"/v1/skills/{skill_id}/versions/{version}/content":{"parameters":[{"$ref":"#/components/parameters/SkillIdPath"},{"$ref":"#/components/parameters/SkillVersionPath"}],"get":{"operationId":"downloadSkillVersion","tags":["Skills"],"summary":"Download skill version","description":"Download the ZIP bundle of one version.","security":[{"BearerAuth":[]},{"AgentsApiKey":[]}],"responses":{"200":{"description":"Skill ZIP bundle","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"unauthorized: missing, malformed, or conflicting API key headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"402":{"description":"spending_limit_exceeded: API key spending limit or organization balance exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"403":{"description":"insufficient_scope (scoped key) or org_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"404":{"description":"not_found: the resource does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}},"503":{"description":"authorization_unavailable, admission_unavailable, executor_unavailable, storage_unavailable, or internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsError"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"SandBase API key. Treat the complete credential as an opaque secret."},"AnthropicApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Supported only by `POST /v1/messages` for Anthropic SDK compatibility"},"GoogleApiKey":{"type":"apiKey","in":"header","name":"x-goog-api-key","description":"Supported by Google Gemini-compatible endpoints. Takes precedence over the other key locations."},"GoogleQueryApiKey":{"type":"apiKey","in":"query","name":"key","description":"Google SDK compatibility fallback. Prefer x-goog-api-key or Authorization because URLs can be logged."},"WebhookApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Accepted by the webhook Events API (/events/webhooks*). Authorization Bearer takes precedence when both are sent."},"AgentsApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Accepted only by Agents platform resources (/v1/agents*, /v1/mcp-connections*, /v1/secrets*, /v1/skills*). If Authorization is also sent, both must carry the same key."}},"parameters":{"AgentIdPath":{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"},"description":"Agent ID (`agt_` prefix)."},"AgentVersionPath":{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Agent version number."},"SessionIdPath":{"name":"session_id","in":"path","required":true,"schema":{"type":"string"},"description":"Session ID (`ses_` prefix)."},"TurnIdPath":{"name":"turn_id","in":"path","required":true,"schema":{"type":"string"},"description":"Turn ID from the turns list."},"FileIdPath":{"name":"file_id","in":"path","required":true,"schema":{"type":"string"},"description":"Attachment ID (`fil_` prefix)."},"MCPConnectionIdPath":{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"},"description":"MCP connection ID (`mcp_` prefix), or builtin:sandbase for the built-in SandBase server."},"SecretIdPath":{"name":"secret_id","in":"path","required":true,"schema":{"type":"string"},"description":"Secret ID (`sec_` prefix)."},"SkillIdPath":{"name":"skill_id","in":"path","required":true,"schema":{"type":"string"},"description":"Skill ID (`skl_` prefix)."},"SkillVersionPath":{"name":"version","in":"path","required":true,"schema":{"type":"string"},"description":"Skill version identifier, such as \"1\"."},"IdempotencyKeyRequired":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Required. 1-128 characters without leading or trailing whitespace. Reuse the same key and body when retrying."},"IdempotencyKeyOptional":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Optional. Send a stable key so retries do not create duplicates."},"OpenAIBeta":{"name":"OpenAI-Beta","in":"header","required":false,"schema":{"type":"string","enum":["agents=v1"]},"description":"Optional OpenAI SDK header. When present it must be agents=v1."},"AgentsLimit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size. Values outside 1-100 return 400."},"SkillLimit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100,"default":20},"description":"Page size. Values outside 0-100 return 400."},"AgentsAfter":{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor. Pass last_id from the previous page."},"AgentsOrder":{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort order by creation time."},"OffsetLimit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":20},"description":"Page size. Defaults to 20; non-numeric or non-positive values fall back to 20. Attachment lists return 400 above 100; other offset lists cap the value at 200."},"Offset":{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Number of records to skip."},"AgentStatusFilter":{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","archived","all"],"default":"active"},"description":"Lifecycle filter. Other values return 400."},"SessionLifecycleFilter":{"name":"lifecycle_status","in":"query","required":false,"schema":{"type":"string","enum":["active","archived","all"],"default":"active"},"description":"Lifecycle filter. Other values return 400."},"GeminiModel":{"name":"model","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Bare Gemini model name, such as gemini-3.5-flash. SandBase adds the google/ catalog prefix."}},"schemas":{"AccountBalance":{"type":"object","required":["org_id","balance","credit_limit","alert_threshold"],"properties":{"org_id":{"type":"string","format":"uuid"},"balance":{"type":"string","description":"Current organization balance in USD, serialized as an exact decimal string."},"credit_limit":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Optional USD credit limit. Null means no credit limit."},"alert_threshold":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Optional USD balance alert threshold."}}},"AccountHistoryPage":{"type":"object","required":["items","total","page","page_size"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AccountHistoryItem"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":1,"maximum":100}}},"AccountHistoryItem":{"type":"object","required":["id","model","type","execution_mode","status","latency_ms","user_cost","prompt_tokens","completion_tokens","total_tokens","cached_tokens","cache_creation_tokens","created_at","api_key_prefix"],"properties":{"id":{"type":"string","description":"Opaque execution ID."},"model":{"type":"string"},"type":{"type":"string"},"execution_mode":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed","timeout"]},"latency_ms":{"type":"integer","minimum":0},"user_cost":{"type":"string","description":"USD cost serialized as an exact decimal string."},"prompt_tokens":{"type":"integer","minimum":0},"completion_tokens":{"type":"integer","minimum":0},"total_tokens":{"type":"integer","minimum":0},"cached_tokens":{"type":"integer","minimum":0},"cache_creation_tokens":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time"},"api_key_prefix":{"type":"string"},"error_message":{"type":"string","description":"Sanitized failure message when recorded."},"error_type":{"type":"string"},"completed_at":{"type":"string","format":"date-time"},"period_settled_cost":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$","description":"Settlement cost attributed to the selected settlement window when available."},"input_params":{"description":"Parsed stored request parameters; omitted when absent or invalid JSON."},"output_result":{"description":"Parsed stored output; numbers retain their JSON precision. Omitted when absent or invalid JSON."}}},"RunRequest":{"type":"object","required":["model"],"description":"Capability-specific request. Resolve the selected model's live input schema before sending fields.","properties":{"model":{"type":"string","description":"Current model or API capability identifier from the SandBase catalog."},"mode":{"type":"string","enum":["auto","sync","async","stream"],"default":"auto","description":"Execution mode when supported by the selected capability. Auto uses the capability's configured default."},"stream":{"type":"boolean","default":false,"description":"Requests streaming output. Equivalent to mode stream and valid only for a capability that supports streaming."},"webhook_url":{"type":"string","format":"uri","description":"Optional public HTTPS callback URL for asynchronous image, video, or audio tasks. It is validated only for those tasks and ignored for other execution types."}},"additionalProperties":true},"RunResponse":{"type":"object","required":["id","status","model"],"properties":{"id":{"type":"string","description":"Opaque execution identifier. Use exactly as returned; no prefix is guaranteed."},"model":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed","timeout"],"description":"A stored completed task can temporarily be reported as running while output transfer is still pending."},"outputs":{"type":"array","description":"Extracted generated outputs when available. Omitted from non-terminal responses and also from completed responses whose output is empty, malformed, unsupported, or not yet transferred.","items":{"type":"object","properties":{"url":{"type":"string","description":"Provider output string, commonly an HTTP URL or data URI; syntax is not revalidated by this projection."},"content_type":{"type":"string"}},"additionalProperties":true}},"error":{"type":"object","description":"Structured sanitized error for failed or timed-out runs when the stored error message is non-empty; otherwise omitted.","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","additionalProperties":true,"description":"Model-specific public usage details when available; omitted for models that do not report them."}}},"UploadMediaRequest":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Image (up to 20 MB), audio (up to 50 MB), or video (up to 500 MB)."},"type":{"type":"string","enum":["image","audio","video"],"description":"Optional category hint. The server still uses the detected MIME type for validation and storage."}}},"UploadMediaResponse":{"type":"object","required":["url","filename","size","type","content_type"],"properties":{"url":{"type":"string","description":"Stored media URL to pass to a supported model input."},"filename":{"type":"string","description":"Original multipart filename."},"size":{"type":"integer","minimum":0,"description":"Uploaded file size in bytes."},"type":{"type":"string","description":"Detected MIME type. This currently matches content_type."},"content_type":{"type":"string","description":"Detected MIME type used when storing the file."},"duration_seconds":{"type":"number","exclusiveMinimum":0,"description":"Media duration in seconds. Returned for audio and video when the duration can be read from the file; omitted otherwise."}}},"CreateAssetRequest":{"type":"object","required":["url","asset_type"],"properties":{"url":{"type":"string","minLength":1,"description":"Source URL forwarded to the asset provider. SandBase requires a non-empty string; the provider must be able to fetch it."},"asset_type":{"type":"string","enum":["Image","Video","Audio"]},"name":{"type":"string"}}},"CreateAssetResponse":{"type":"object","required":["id","asset_url","asset_type","created_at"],"properties":{"id":{"type":"string"},"asset_url":{"type":"string","description":"Persistent asset:// reference used in generation requests."},"asset_type":{"type":"string","enum":["Image","Video","Audio"]},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"GetAssetResponse":{"type":"object","required":["id","external_id","asset_url","status","asset_type","download_url","created_at"],"properties":{"id":{"type":"string"},"external_id":{"type":"string"},"asset_url":{"type":"string","description":"Persistent asset:// reference used in generation requests."},"asset_type":{"type":"string","enum":["Image","Video","Audio"]},"name":{"type":"string"},"status":{"type":"string","description":"Provider-reported asset status, returned without normalization."},"download_url":{"type":"string","description":"Provider-returned download URL. It can be empty until the provider makes a URL available."},"created_at":{"type":"string","format":"date-time"}}},"Webhook":{"type":"object","required":["id","name","url","resourceType","events","enabled","createdAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"resourceType":{"type":"string","description":"model for new registrations. Retired types (session, sandbox, template) can still appear on old registrations."},"events":{"type":"array","items":{"type":"string"},"description":"Empty means all events in the resource type."},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"WebhookCreated":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","required":["signatureSecret"],"properties":{"signatureSecret":{"type":"string","description":"HMAC signing secret. Returned only in this response."}}}]},"WebhookCreateRequest":{"type":"object","required":["name","url","resourceType"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri","description":"HTTP(S) endpoint. Use HTTPS in production."},"resourceType":{"type":"string","enum":["model"]},"events":{"type":"array","items":{"type":"string","enum":["model.generation.completed","model.generation.failed","model.generation.timeout","model.generation.cancelled"]},"description":"Empty or omitted means all current and future events in the resource type."},"enabled":{"type":"boolean","default":true},"signatureSecret":{"type":"string","description":"Optional. Omit to let SandBase generate a high-entropy secret."}}},"WebhookUpdateRequest":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"resourceType":{"type":"string","enum":["model"]},"events":{"type":"array","items":{"type":"string","enum":["model.generation.completed","model.generation.failed","model.generation.timeout","model.generation.cancelled"]}},"enabled":{"type":"boolean"}}},"WebhookError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string"}}},"TaskCostResponse":{"type":"object","required":["id","status","settled","currency","cost","estimated_cost","usage"],"properties":{"id":{"type":"string","description":"SandBase task ID."},"status":{"type":"string","enum":["pending","running","completed","failed","timeout"]},"settled":{"type":"boolean","description":"Whether final cost settlement has completed."},"currency":{"type":"string","enum":["USD"]},"cost":{"type":"string","pattern":"^\\d+\\.\\d{6}$","description":"USD amount with six decimal places. Not final while settled is false.","example":"0.001234"},"estimated_cost":{"type":"string","pattern":"^\\d+\\.\\d{6}$","description":"Best-effort USD estimate with six decimal places. Informational while settled is false; matches cost once settled is true.","example":"0.001234"},"usage":{"$ref":"#/components/schemas/TaskCostUsage"},"pricing":{"$ref":"#/components/schemas/TaskCostPricing"}}},"TaskCostPricing":{"type":"object","description":"Present only after settlement when a discount breakdown was recorded. original_cost minus discount_amount equals cost.","required":["original_cost","discount_amount","discount_percent"],"properties":{"original_cost":{"type":"string","pattern":"^\\d+\\.\\d{6}$","description":"USD cost before discounts, with six decimal places."},"discount_amount":{"type":"string","pattern":"^\\d+\\.\\d{6}$","description":"USD discount applied, with six decimal places."},"discount_percent":{"type":"number","minimum":0,"description":"Discount percentage, for example 25 for 25 percent off."},"discount_type":{"type":"string","description":"Kind of discount applied. Omitted when not recorded."}}},"TaskCostUsage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens","cached_tokens","cache_creation_tokens","reasoning_tokens"],"properties":{"prompt_tokens":{"type":"integer","minimum":0},"completion_tokens":{"type":"integer","minimum":0},"total_tokens":{"type":"integer","minimum":0},"cached_tokens":{"type":"integer","minimum":0},"cache_creation_tokens":{"type":"integer","minimum":0},"reasoning_tokens":{"type":"integer","minimum":0}}},"TaskCostError":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"APIPassthroughResponse":{"description":"Capability-specific response. Its shape is defined by the selected live catalog capability and may be an object, array, or scalar."},"APIPassthroughError":{"description":"Route-resolution, authentication, admission, or unified-pipeline error.","anyOf":[{"$ref":"#/components/schemas/TaskCostError"},{"$ref":"#/components/schemas/APIKeyScopeError"},{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}]},"ModelListResponse":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/OpenAIModelListItem"}}}},"OpenAIModelListItem":{"type":"object","required":["id","object","created","owned_by"],"properties":{"id":{"type":"string","description":"Logical model name used in inference requests."},"object":{"type":"string","const":"model"},"created":{"type":"integer","description":"Unix creation timestamp."},"owned_by":{"type":"string","description":"Representative enabled provider or sandbase."}}},"ModelDetail":{"type":"object","description":"Detailed model response. Pricing is returned only in the optional model_card object.","required":["id","name","display_name","vendor","description","type","capability_tags","skills","unified_schema","execution_mode","supported_modes","run_count","sort_order","published_at","vendor_slug","model_slug","enabled","featured","created_at","examples"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal model resource ID. Use name in inference requests."},"name":{"type":"string","example":"openai/gpt-5.6-luna"},"display_name":{"type":"string","example":"GPT-5.6 Luna"},"vendor":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"capability_tags":{"type":["array","null"],"items":{"type":"string"}},"skills":{"type":"array","description":"String capability tags derived from capability_tags; empty when tags are absent or invalid.","items":{"type":"string"}},"unified_schema":{"type":["object","null"],"additionalProperties":true},"execution_mode":{"type":"string"},"supported_modes":{"type":["array","null"],"items":{"type":"string"}},"run_count":{"type":"integer"},"sort_order":{"type":"integer"},"published_at":{"type":["string","null"],"format":"date-time"},"vendor_slug":{"type":"string"},"model_slug":{"type":"string"},"enabled":{"type":"boolean"},"featured":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"model_card":{"$ref":"#/components/schemas/ModelCard"},"examples":{"type":"array","items":{"$ref":"#/components/schemas/ModelExample"}}}},"ModelExample":{"type":"object","required":["id","is_default","created_at"],"properties":{"id":{"type":"string"},"is_default":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"input_snapshot":{"description":"Parsed JSON input snapshot. Omitted when absent or invalid."},"output_snapshot":{"description":"Parsed JSON output snapshot. Omitted when absent or invalid."}}},"ModelCard":{"type":"object","description":"Model pricing and presentation data.","required":["base_price","prompt_token_price","completion_token_price","cache_read_multiplier","cache_write_multiplier","cache_write_1h_multiplier","reasoning_price","price_formula","markup_ratio","readme","cover_url"],"properties":{"base_price":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"prompt_token_price":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"completion_token_price":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"cache_read_multiplier":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"cache_write_multiplier":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"cache_write_1h_multiplier":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"reasoning_price":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"price_formula":{"type":"string"},"markup_ratio":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"readme":{"type":"string"},"cover_url":{"type":"string"}}},"ResponsesRequest":{"type":"object","required":["model"],"additionalProperties":true,"description":"OpenAI-compatible request. SandBase rewrites model for the selected provider and preserves other fields.","properties":{"model":{"type":"string","description":"Model identifier from the Models API."},"input":{"description":"Text, message items, or other input supported by the selected model and provider."},"instructions":{"type":"string"},"stream":{"type":"boolean","default":false,"description":"Return sanitized OpenAI Responses Server-Sent Events."},"background":{"type":"boolean"},"include":{"type":"array","items":{"type":"string"}},"max_output_tokens":{"type":"integer","minimum":1},"max_tool_calls":{"type":"integer","minimum":1},"metadata":{"type":"object","additionalProperties":true},"parallel_tool_calls":{"type":"boolean"},"previous_response_id":{"type":"string"},"reasoning":{"type":"object","additionalProperties":true},"service_tier":{"type":"string"},"store":{"type":"boolean"},"temperature":{"type":"number"},"text":{"type":"object","additionalProperties":true},"tool_choice":{"oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}]},"tools":{"type":"array","items":{"type":"object","additionalProperties":true}},"top_logprobs":{"type":"integer"},"top_p":{"type":"number"},"truncation":{"type":"string"},"user":{"type":"string"}}},"ResponsesResponse":{"type":"object","additionalProperties":false,"description":"Public OpenAI Responses fields retained by SandBase. Provider-specific top-level fields are removed; output items remain provider-compatible free-form objects.","properties":{"id":{"type":"string"},"object":{"type":"string"},"created_at":{"type":"integer"},"status":{"type":"string"},"error":{"type":["object","null"],"additionalProperties":true},"incomplete_details":{"type":["object","null"],"additionalProperties":true},"instructions":{"type":["string","null"]},"max_output_tokens":{"type":["integer","null"]},"max_tool_calls":{"type":["integer","null"]},"model":{"type":"string"},"output":{"type":"array","items":{"type":"object","additionalProperties":true}},"parallel_tool_calls":{"type":"boolean"},"previous_response_id":{"type":["string","null"]},"reasoning":{"type":["object","null"],"additionalProperties":true},"store":{"type":"boolean"},"temperature":{"type":["number","null"]},"text":{"type":"object","additionalProperties":true},"tool_choice":{},"tools":{"type":"array","items":{"type":"object","additionalProperties":true}},"top_logprobs":{"type":"integer"},"top_p":{"type":["number","null"]},"truncation":{"type":"string"},"usage":{"type":"object","additionalProperties":false,"required":["input_tokens","output_tokens","total_tokens","input_tokens_details","output_tokens_details"],"properties":{"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"total_tokens":{"type":"integer","minimum":0},"input_tokens_details":{"type":"object","additionalProperties":false,"required":["cached_tokens"],"properties":{"cached_tokens":{"type":"integer","minimum":0}}},"output_tokens_details":{"type":"object","additionalProperties":false,"required":["reasoning_tokens"],"properties":{"reasoning_tokens":{"type":"integer","minimum":0}}}}},"metadata":{"type":"object","additionalProperties":true},"service_tier":{"type":"string"},"user":{"type":"string"},"background":{"type":"boolean"}}},"ChatCompletionRequest":{"type":"object","required":["model","messages"],"additionalProperties":true,"description":"OpenAI-compatible request. Additional provider-compatible fields are forwarded when supported by the selected route.","properties":{"model":{"type":"string","description":"Model identifier","example":"openai/gpt-5.4"},"messages":{"type":"array","items":{"type":"object","required":["role"],"additionalProperties":true,"properties":{"role":{"type":"string","description":"Message role supported by the selected provider, such as system, developer, user, assistant, or tool."},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"null"}]},"name":{"type":"string"},"tool_calls":{"type":"array"},"tool_call_id":{"type":"string"}}}},"temperature":{"type":"number","minimum":0,"maximum":2,"default":1},"top_p":{"type":"number"},"max_tokens":{"type":"integer"},"stream":{"type":"boolean","default":false},"stop":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"tools":{"type":"array","items":{"type":"object"}},"mcp_servers":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/MCPServer"}},"tool_choice":{"oneOf":[{"type":"string"},{"type":"object"}]},"parallel_tool_calls":{"type":"boolean"},"user":{"type":"string"},"response_format":{"type":"object"},"reasoning_effort":{"type":"string","description":"Provider-compatible reasoning effort setting."},"reasoning":{"type":"object","additionalProperties":true,"description":"Reasoning configuration; common fields include effort and max_tokens."},"thinking":{"type":"object","additionalProperties":true,"description":"Thinking configuration; common fields include type and budget_tokens."},"extra_body":{"type":"object","additionalProperties":true,"description":"Provider-specific parameters used when SandBase translates the request between protocols."},"n":{"type":"integer","default":1},"presence_penalty":{"type":"number"},"frequency_penalty":{"type":"number"},"stream_options":{"type":"object","properties":{"include_usage":{"type":"boolean"}}}}},"ChatCompletionResponse":{"type":"object","required":["id","object","created","model","choices","usage"],"additionalProperties":true,"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","required":["index","message","finish_reason","logprobs"],"additionalProperties":true,"properties":{"index":{"type":"integer"},"message":{"type":"object","required":["role","content"],"additionalProperties":true,"properties":{"role":{"type":"string"},"content":{"type":["string","null"]},"tool_calls":{"type":"array"},"reasoning_content":{"type":["string","null"]}}},"finish_reason":{"type":["string","null"],"description":"Provider finish reason. Values can vary by model and provider."},"logprobs":{"description":"Token log probabilities when requested and supported; otherwise null."}}}},"usage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens","prompt_tokens_details","completion_tokens_details"],"additionalProperties":true,"properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"prompt_tokens_details":{"type":"object","required":["cached_tokens","cache_write_tokens"],"properties":{"cached_tokens":{"type":"integer"},"cache_write_tokens":{"type":"integer"}}},"completion_tokens_details":{"type":"object","required":["reasoning_tokens"],"properties":{"reasoning_tokens":{"type":"integer"}}}}}}},"ChatCompletionError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","code","param"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":["null","string"]},"param":{"type":["null","string"]}}}}},"AnthropicMessageResponse":{"type":"object","additionalProperties":true,"description":"Anthropic-compatible response forwarded from the selected provider. Fields can vary with beta features.","properties":{"id":{"type":"string"},"type":{"type":"string","const":"message"},"role":{"type":"string","const":"assistant"},"model":{"type":"string"},"content":{"type":"array","items":{"type":"object","additionalProperties":true}},"stop_reason":{"type":["string","null"]},"stop_sequence":{"type":["string","null"]},"usage":{"type":"object","additionalProperties":true,"properties":{"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"cache_read_input_tokens":{"type":"integer","minimum":0},"cache_creation_input_tokens":{"type":"integer","minimum":0},"cache_creation":{"type":"object","additionalProperties":true,"properties":{"ephemeral_5m_input_tokens":{"type":"integer","minimum":0},"ephemeral_1h_input_tokens":{"type":"integer","minimum":0}}}}}}},"AnthropicError":{"type":"object","required":["type","error"],"properties":{"type":{"type":"string","const":"error"},"error":{"type":"object","required":["type","message"],"additionalProperties":true,"properties":{"type":{"type":"string","description":"Anthropic error type, such as invalid_request_error, authentication_error, permission_error, request_too_large, rate_limit_error, or api_error."},"message":{"type":"string"}}}}},"GeminiGenerateContentRequest":{"type":"object","additionalProperties":true,"description":"Google Gemini GenerateContent request. Native passthrough mappings preserve provider-defined fields; translated mappings use the documented capability subset.","properties":{"contents":{"type":"array","items":{"$ref":"#/components/schemas/GeminiContent"}},"systemInstruction":{"$ref":"#/components/schemas/GeminiContent"},"generationConfig":{"type":"object","additionalProperties":true,"properties":{"temperature":{"type":"number"},"topP":{"type":"number"},"topK":{"type":"integer"},"maxOutputTokens":{"type":"integer"},"stopSequences":{"type":"array","items":{"type":"string"}},"candidateCount":{"type":"integer","description":"Translated mappings accept only 1 when supplied; native passthrough mappings preserve the provider request."},"seed":{"type":"integer"},"presencePenalty":{"type":"number"},"frequencyPenalty":{"type":"number"},"responseMimeType":{"type":"string","enum":["text/plain","application/json","text/x.enum"]},"responseSchema":{"type":"object","additionalProperties":true},"responseModalities":{"type":"array","items":{"type":"string"},"description":"Native image mappings support provider image modalities. Other translated mappings may support TEXT only."},"thinkingConfig":{"type":"object","additionalProperties":true}}},"tools":{"type":"array","items":{"type":"object","additionalProperties":true}},"toolConfig":{"type":"object","additionalProperties":true},"safetySettings":{"type":"array","items":{"type":"object","additionalProperties":true}},"cachedContent":{"type":"string","description":"Passed through when the selected provider supports Gemini context caching."}}},"GeminiContent":{"type":"object","additionalProperties":true,"properties":{"role":{"type":"string","enum":["user","model"]},"parts":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Text, image inlineData, public HTTP(S) image fileData, functionCall, or functionResponse part."}}}},"GeminiGenerateContentResponse":{"type":"object","additionalProperties":true,"properties":{"candidates":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"content":{"$ref":"#/components/schemas/GeminiContent"},"finishReason":{"type":"string"},"index":{"type":"integer"},"safetyRatings":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"usageMetadata":{"type":"object","additionalProperties":true,"properties":{"promptTokenCount":{"type":"integer","minimum":0},"candidatesTokenCount":{"type":"integer","minimum":0},"totalTokenCount":{"type":"integer","minimum":0},"cachedContentTokenCount":{"type":"integer","minimum":0},"thoughtsTokenCount":{"type":"integer","minimum":0}}},"promptFeedback":{"type":"object","additionalProperties":true},"modelVersion":{"type":"string"},"responseId":{"type":"string"}}},"GeminiInteractionRequest":{"type":"object","required":["model","input"],"additionalProperties":true,"description":"Google Interactions request. Except for fields used for routing and lifecycle control, fields are forwarded to\nthe selected upstream. Agent interactions are not supported. background and stream cannot both be true.\n","properties":{"model":{"type":"string","minLength":1,"description":"Logical SandBase model name. The response echoes this name instead of an upstream model identifier."},"input":{"description":"Google Interactions input; it can be text, an object, or an array of typed input items."},"stream":{"type":"boolean","default":false,"description":"Requests an SSE event stream when the selected model supports it."},"background":{"type":"boolean","default":false,"description":"Requests durable background execution and an immediately pollable in_progress Interaction."},"previous_interaction_id":{"type":"string","description":"Previous Interaction ID. SandBase keeps the request on the same upstream provider when the mapping is still available."},"store":{"type":"boolean","description":"Forwarded upstream. Stored upstream state may be required for previous_interaction_id."},"system_instruction":{"type":"string"},"tools":{"type":"array","items":{"type":"object","additionalProperties":true}},"generation_config":{"type":"object","additionalProperties":true},"response_format":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"response_modalities":{"type":"array","items":{"type":"string"}}}},"GeminiInteraction":{"type":"object","required":["id","object","model","status"],"additionalProperties":true,"properties":{"id":{"type":"string","description":"Upstream Interaction ID used by GET and previous_interaction_id."},"object":{"type":"string","const":"interaction"},"model":{"type":"string","description":"Logical SandBase model name supplied by the client."},"role":{"type":"string"},"status":{"type":"string","enum":["in_progress","requires_action","completed","failed","cancelled","incomplete"]},"created":{"type":"string"},"updated":{"type":"string"},"steps":{"type":"array","description":"Polymorphic Google Interaction steps. Unknown step and content types are preserved.","items":{"type":"object","additionalProperties":true}},"usage":{"$ref":"#/components/schemas/GeminiInteractionUsage"}}},"GeminiInteractionUsage":{"type":"object","additionalProperties":true,"properties":{"total_input_tokens":{"type":"integer","minimum":0},"total_output_tokens":{"type":"integer","minimum":0},"total_cached_tokens":{"type":"integer","minimum":0},"total_thought_tokens":{"type":"integer","minimum":0},"total_tool_use_tokens":{"type":"integer","minimum":0},"total_tokens":{"type":"integer","minimum":0},"input_tokens_by_modality":{"type":"array","items":{"$ref":"#/components/schemas/GeminiInteractionModalityUsage"}},"output_tokens_by_modality":{"type":"array","items":{"$ref":"#/components/schemas/GeminiInteractionModalityUsage"}}}},"GeminiInteractionModalityUsage":{"type":"object","required":["modality","tokens"],"additionalProperties":true,"properties":{"modality":{"type":"string"},"tokens":{"type":"integer","minimum":0}}},"GeminiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"additionalProperties":true,"properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string","description":"Google canonical error status, such as INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED, NOT_FOUND, RESOURCE_EXHAUSTED, INTERNAL, UNAVAILABLE, or DEADLINE_EXCEEDED."}}}}},"VolcengineContentsGenerationRequest":{"type":"object","required":["model","content"],"additionalProperties":true,"properties":{"model":{"type":"string","enum":["doubao-seedance-2-0-260128","doubao-seedance-2-0-fast-260128","doubao-seedance-2-5-260628"]},"content":{"type":"array","minItems":1,"description":"Must include text. Media items select image-to-video or reference-to-video mode according to role.","items":{"$ref":"#/components/schemas/VolcengineContentItem"}},"callback_url":{"type":"string","minLength":1,"description":"Receives the terminal task response."},"duration":{"type":"integer"},"resolution":{"type":"string"},"ratio":{"type":"string"},"generate_audio":{"type":"boolean"},"seed":{"type":"integer"},"camera_fixed":{"type":"boolean"},"watermark":{"type":"boolean"},"draft":{"type":"boolean"},"return_last_frame":{"type":"boolean"},"service_tier":{"type":"string"},"execution_expires_after":{"type":"integer"},"frames":{"type":"integer"},"framespersecond":{"type":"integer"},"tools":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"VolcengineContentItem":{"type":"object","required":["type"],"additionalProperties":true,"properties":{"type":{"type":"string","enum":["text","image_url","video_url","audio_url"]},"text":{"type":"string"},"image_url":{"oneOf":[{"type":"string"},{"type":"object","required":["url"],"properties":{"url":{"type":"string"}}}]},"video_url":{"oneOf":[{"type":"string"},{"type":"object","required":["url"],"properties":{"url":{"type":"string"}}}]},"audio_url":{"oneOf":[{"type":"string"},{"type":"object","required":["url"],"properties":{"url":{"type":"string"}}}]},"role":{"type":"string","enum":["first_frame","last_frame","reference_image","reference_video","reference_audio"]}}},"VolcengineTaskCreated":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}},"VolcengineTask":{"type":"object","required":["id","model","status","created_at","updated_at","content","usage"],"additionalProperties":true,"properties":{"id":{"type":"string"},"model":{"type":"string"},"status":{"type":"string","enum":["queued","running","cancelled","succeeded","failed","expired"]},"created_at":{"type":"integer","format":"int64","description":"Unix timestamp in seconds."},"updated_at":{"type":"integer","format":"int64","description":"Unix timestamp in seconds."},"content":{"type":"object","properties":{"video_url":{"type":"string"},"last_frame_url":{"type":"string"},"file_url":{"type":"string"}}},"usage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens","prompt_tokens_details","completion_tokens_details"],"properties":{"prompt_tokens":{"type":"integer","minimum":0},"completion_tokens":{"type":"integer","minimum":0},"total_tokens":{"type":"integer","minimum":0},"prompt_tokens_details":{"type":"object","additionalProperties":true},"completion_tokens_details":{"type":"object","additionalProperties":true}}},"error":{"$ref":"#/components/schemas/VolcengineTaskFailure"},"failure_reason":{"$ref":"#/components/schemas/VolcengineTaskFailure"}}},"VolcengineTaskFailure":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"VolcengineError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","type"],"properties":{"code":{"type":"string","description":"InvalidParameter, AuthenticationError, PermissionDenied, ResourceNotFound, RateLimitExceeded, or InternalServiceError."},"message":{"type":"string"},"type":{"type":"string","description":"HTTP-style Volcengine error type."}}}}},"EmbeddingRequest":{"type":"object","required":["model","input"],"additionalProperties":true,"description":"OpenAI-compatible request. Additional provider-compatible fields are forwarded unchanged.","properties":{"model":{"type":"string","description":"Embedding model identifier.","example":"alibaba/text-embedding-v4"},"input":{"description":"Text, token IDs, or a batch of texts or token-ID arrays to embed. Provider limits apply.","oneOf":[{"type":"string","example":"SandBase provides a unified API for AI models, agents, and developer tools."},{"type":"array","items":{"type":"string"},"example":["First document","Second document"]},{"type":"array","items":{"type":"integer"}},{"type":"array","items":{"type":"array","items":{"type":"integer"}}}]},"dimensions":{"type":"integer","minimum":1,"description":"Optional output dimension when supported by the selected model. SandBase does not impose a universal dimension list.","example":1024},"encoding_format":{"type":"string","description":"Requested embedding encoding. Support is provider- and model-specific.","enum":["float","base64"],"default":"float"}}},"EmbeddingResponse":{"type":"object","required":["object","data","model","usage"],"additionalProperties":true,"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","required":["object","index","embedding"],"additionalProperties":true,"properties":{"object":{"type":"string","enum":["embedding"]},"index":{"type":"integer"},"embedding":{"oneOf":[{"type":"array","items":{"type":"number","format":"float"}},{"type":"string","description":"Base64-encoded vector when encoding_format is base64."}]}}}},"model":{"type":"string","example":"alibaba/text-embedding-v4"},"usage":{"type":"object","required":["prompt_tokens","total_tokens"],"additionalProperties":true,"properties":{"prompt_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}},"EmbeddingError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","code","param"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":["null","string"]},"param":{"type":["null","string"]}}}}},"ImageGenerationRequest":{"type":"object","required":["model","prompt"],"additionalProperties":true,"properties":{"model":{"type":"string","enum":["gpt-image-2","gpt-image-2.5-flare","gpt-image-2.5-sunburst"]},"prompt":{"type":"string","minLength":1},"n":{"type":"integer","minimum":1},"size":{"type":"string","description":"Output size supported by the selected model, such as 1024x1024, 1024x1536, 1536x1024, or auto."},"quality":{"type":"string","description":"Output quality supported by the selected model, such as low, medium, high, or auto."},"background":{"type":"string","description":"Background setting such as transparent, opaque, or auto."},"output_format":{"type":"string","description":"Output encoding such as png, webp, or jpeg."},"output_compression":{"type":"integer","minimum":0,"maximum":100},"moderation":{"type":"string"},"user":{"type":"string"},"stream":{"type":"boolean","const":false,"default":false,"description":"Streaming is not supported by this SandBase endpoint."},"mode":{"type":"string","const":"sync","default":"sync"}}},"ImageEditRequest":{"type":"object","required":["model","prompt","image"],"additionalProperties":true,"properties":{"model":{"type":"string","enum":["gpt-image-2","gpt-image-2.5-flare","gpt-image-2.5-sunburst"]},"prompt":{"type":"string","minLength":1},"image":{"oneOf":[{"type":"string","format":"binary"},{"type":"array","items":{"type":"string","format":"binary"}}],"description":"Source image file. Repeat the multipart field to provide multiple images."},"mask":{"type":"string","format":"binary"},"n":{"type":"integer","minimum":1},"size":{"type":"string"},"quality":{"type":"string"},"background":{"type":"string"},"input_fidelity":{"type":"string"},"output_format":{"type":"string"},"output_compression":{"type":"integer","minimum":0,"maximum":100},"user":{"type":"string"},"stream":{"type":"boolean","const":false,"default":false,"description":"Streaming is not supported by this SandBase endpoint."},"mode":{"type":"string","const":"sync","default":"sync"}}},"ImagesResponse":{"type":"object","required":["data","usage"],"additionalProperties":true,"properties":{"created":{"type":"integer"},"data":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":true,"anyOf":[{"required":["b64_json"]},{"required":["url"]}],"properties":{"b64_json":{"type":"string","description":"Base64-encoded image data."},"url":{"type":"string","format":"uri"},"revised_prompt":{"type":"string"}}}},"usage":{"type":"object","required":["input_tokens","output_tokens","total_tokens","input_tokens_details"],"additionalProperties":true,"properties":{"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"total_tokens":{"type":"integer","minimum":0},"input_tokens_details":{"type":"object","required":["text_tokens","image_tokens"],"additionalProperties":true,"properties":{"text_tokens":{"type":"integer","minimum":0},"image_tokens":{"type":"integer","minimum":0},"cached_text_tokens":{"type":"integer","minimum":0},"cached_image_tokens":{"type":"integer","minimum":0},"cached_tokens":{"type":"integer","minimum":0}}}}}}},"OpenAIImagesError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","code","param"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":["null","string"]},"param":{"type":["null","string"]}}}}},"APIKeyScopeError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","const":"insufficient_scope"},"message":{"type":"string"},"request_id":{"type":"string"}}}}},"MCPServer":{"type":"object","required":["name","type","url"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"type":{"type":"string","enum":["url"]},"url":{"type":"string","format":"uri"}}},"AgentsError":{"type":"object","description":"Error envelope for Agents platform resources. message is a fixed, safe sentence for each code.","required":["error"],"properties":{"error":{"type":"object","required":["type","code","param","message"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","server_error"]},"code":{"type":"string","description":"Stable machine-readable code. Unknown future codes should be treated by HTTP status.","enum":["unauthorized","insufficient_scope","authorization_unavailable","org_disabled","spending_limit_exceeded","quota_exceeded","concurrency_limit","admission_unavailable","invalid_request","not_found","conflict","session_input_pending","session_input_expired","session_environment_unavailable","tenant_provisioning_failed","tenant_unavailable","executor_rejected","executor_unavailable","executor_contract_error","skill_not_found","skill_unavailable","skill_runtime_incompatible","storage_unavailable","internal_error","request_too_large"]},"param":{"type":"null"},"message":{"type":"string"}}}}},"AgentsCursorList":{"type":"object","required":["object","data","has_more","first_id","last_id"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"has_more":{"type":"boolean"},"first_id":{"type":["string","null"]},"last_id":{"type":["string","null"],"description":"Pass as after to read the next page."}}},"AgentsOffsetList":{"type":"object","required":["data","total","limit","offset"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"EmptyObject":{"type":"object","additionalProperties":false,"maxProperties":0},"RowVersionRequest":{"type":"object","additionalProperties":false,"required":["row_version"],"properties":{"row_version":{"type":"integer","minimum":1,"description":"The row_version you last read. A stale value returns 409."}}},"AgentSkillRef":{"type":"object","additionalProperties":false,"required":["skill_id"],"properties":{"skill_id":{"type":"string","description":"Skill ID (`skl_` prefix) owned by your organization or available from the public Skills catalog."},"version":{"type":["string","null"],"description":"Pinned Skill version. For a new binding, null resolves the current default when the Agent is saved. For an existing binding, null retains its pinned version; pass an explicit version to upgrade."}}},"AgentMCPConnectionRef":{"type":"object","additionalProperties":false,"required":["connection_id","server_label"],"properties":{"connection_id":{"type":"string","description":"MCP connection ID (`mcp_` prefix), or builtin:sandbase for the built-in SandBase server."},"server_label":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_-]{0,63}$","description":"Label unique within the Agent."},"allowed_tools":{"type":["array","null"],"maxItems":256,"items":{"type":"string","minLength":1,"maxLength":128},"description":"null allows every tool; an empty array allows none."},"required":{"type":"boolean","description":"Whether the Session must load this server."}}},"AgentFunctionTool":{"type":"object","additionalProperties":false,"required":["type","name","description","parameters"],"description":"Saved function tool. Runs that request a client-side tool result are not supported yet.","properties":{"type":{"type":"string","const":"function"},"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string"},"parameters":{"type":"object","description":"JSON Schema whose type is object."},"defer_loading":{"type":"boolean"}}},"AgentWebSearchTool":{"type":"object","additionalProperties":false,"required":["type"],"description":"At most one per Agent. Sessions currently require mode disabled.","properties":{"type":{"type":"string","const":"web_search"},"mode":{"type":"string","enum":["disabled","cached","live"]},"context_size":{"type":"string","enum":["low","medium","high"]},"allowed_domains":{"type":"array","items":{"type":"string"}},"location":{"type":"object","additionalProperties":false,"properties":{"city":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"timezone":{"type":"string"}}}}},"AgentText":{"type":"object","additionalProperties":false,"properties":{"format":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["text","json_schema"]},"schema":{"type":"object","description":"Required for json_schema; its type must be object."}}},"verbosity":{"type":"string","enum":["low","medium","high"]}}},"AgentReasoning":{"type":"object","additionalProperties":false,"properties":{"effort":{"type":["string","null"],"enum":["none","minimal","low","medium","high","xhigh","max",null]},"summary":{"type":["string","null"],"enum":["concise","detailed","auto",null]}}},"AgentConfigFields":{"type":"object","properties":{"name":{"type":"string","maxLength":128},"model":{"type":"string","minLength":1,"maxLength":200,"description":"Model ID from the Models API, such as deepseek/deepseek-v4-flash."},"instructions":{"type":"string","maxLength":262144},"description":{"type":"string","maxLength":4096},"metadata":{"type":"object","maxProperties":16,"additionalProperties":{"type":"string","maxLength":512},"description":"Keys up to 64 characters."},"service_tier":{"type":"string","enum":["auto","default","flex","priority","fast"],"default":"auto"},"runtime_profile":{"type":"string","enum":["codex","claude","mcode"],"default":"codex"},"tools":{"type":"array","maxItems":64,"items":{"oneOf":[{"$ref":"#/components/schemas/AgentFunctionTool"},{"$ref":"#/components/schemas/AgentWebSearchTool"}]}},"text":{"$ref":"#/components/schemas/AgentText"},"reasoning":{"$ref":"#/components/schemas/AgentReasoning"},"skills":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkillRef"}},"mcp_connections":{"type":"array","maxItems":32,"items":{"$ref":"#/components/schemas/AgentMCPConnectionRef"},"description":"Omission selects builtin:sandbase on create. An explicit array replaces the selection; [] disables all MCP tools. Null is rejected."}}},"AgentCreateRequest":{"allOf":[{"$ref":"#/components/schemas/AgentConfigFields"},{"type":"object","required":["model"],"properties":{"note":{"type":"string","description":"Optional change note recorded on version 1."},"multi_agent":{"type":"null","description":"Only null is accepted."}}}]},"AgentUpdateRequest":{"type":"object","additionalProperties":false,"description":"SDK-style partial update. description and note are not accepted here; use PATCH for them.","properties":{"name":{"type":"string","maxLength":128},"model":{"type":"string","minLength":1,"maxLength":200},"instructions":{"type":"string","maxLength":262144},"metadata":{"type":"object","maxProperties":16,"additionalProperties":{"type":"string","maxLength":512}},"service_tier":{"type":"string","enum":["auto","default","flex","priority","fast"]},"runtime_profile":{"type":"string","enum":["codex","claude","mcode"]},"tools":{"type":"array","maxItems":64,"items":{"type":"object"}},"text":{"$ref":"#/components/schemas/AgentText"},"reasoning":{"$ref":"#/components/schemas/AgentReasoning"},"skills":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkillRef"}},"mcp_connections":{"type":"array","items":{"$ref":"#/components/schemas/AgentMCPConnectionRef"}}}},"AgentReplaceRequest":{"allOf":[{"$ref":"#/components/schemas/AgentConfigFields"},{"type":"object","required":["row_version"],"description":"Supplied fields replace saved values; explicit null values are rejected.","properties":{"note":{"type":"string","description":"Change note recorded on the new version."},"row_version":{"type":"integer","minimum":1}}}]},"AgentRowVersionRequest":{"$ref":"#/components/schemas/RowVersionRequest"},"AgentRestoreRequest":{"type":"object","additionalProperties":false,"required":["source_version","row_version"],"properties":{"source_version":{"type":"integer","minimum":1,"description":"Version whose configuration becomes the new current version."},"row_version":{"type":"integer","minimum":1}}},"AgentCloneRequest":{"type":"object","additionalProperties":false,"properties":{"version":{"type":"integer","minimum":1,"description":"Catalog version to copy. Defaults to the current public version."},"name":{"type":"string","maxLength":128,"description":"Name for the new Agent."}}},"Agent":{"type":"object","required":["id","object","model","name","instructions","tools","text","reasoning","service_tier","multi_agent","visibility","status","version","row_version","projection_status","runtime_profile","description","metadata","mcp_connections","skills","created_at","updated_at","archived_at"],"properties":{"id":{"type":"string","description":"Agent ID (`agt_` prefix)."},"object":{"type":"string","const":"agent"},"model":{"type":"string"},"name":{"type":["string","null"]},"instructions":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object"}},"text":{"$ref":"#/components/schemas/AgentText"},"reasoning":{"type":"object"},"service_tier":{"type":"string"},"multi_agent":{"type":"object","description":"Always reports enabled false."},"visibility":{"type":"string","enum":["private","public"]},"status":{"type":"string","enum":["active","archived"]},"version":{"type":"integer","description":"Current version number."},"row_version":{"type":"integer","description":"Compare-and-set token for PATCH, archive, unarchive, and restore."},"projection_status":{"type":"string","description":"Whether the current version is ready for execution. Sessions require ready."},"runtime_profile":{"type":"string","enum":["codex","claude","mcode"]},"description":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"mcp_connections":{"type":"array","items":{"$ref":"#/components/schemas/AgentMCPConnectionRef"}},"skills":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkillRef"}},"created_at":{"type":"integer","description":"Unix seconds."},"updated_at":{"type":"integer","description":"Unix seconds."},"archived_at":{"type":["integer","null"],"description":"Unix seconds."},"failure_code":{"type":"string"}}},"AgentList":{"allOf":[{"$ref":"#/components/schemas/AgentsCursorList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}]},"AgentDeleted":{"type":"object","required":["id","object","deleted"],"properties":{"id":{"type":"string"},"object":{"type":"string","const":"agent.deleted"},"deleted":{"type":"boolean","const":true}}},"AgentVersion":{"type":"object","required":["version","agent","checksum","created_at"],"properties":{"version":{"type":"integer"},"agent":{"type":"object","description":"Saved configuration document of this version."},"checksum":{"type":"string"},"note":{"type":"string","description":"Present only when the change that created this version sent a note."},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 string, unlike the Unix-second timestamps on Agent objects."},"failure_code":{"type":"string"}}},"AgentVersionList":{"allOf":[{"$ref":"#/components/schemas/AgentsOffsetList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentVersion"}}}}]},"AgentCatalogEntry":{"type":"object","required":["id","object","visibility","version","name","description","model","created_at","updated_at"],"properties":{"id":{"type":"string"},"object":{"type":"string","const":"agent"},"visibility":{"type":"string","const":"public"},"version":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"model":{"type":"string"},"skills":{"type":"array","items":{"type":"object"}},"configuration":{"type":"object","description":"Read-only configuration (name, description, model, instructions, runtime_profile, metadata, tools, text, reasoning, skills)."},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"failure_code":{"type":"string"}}},"AgentCatalogList":{"allOf":[{"$ref":"#/components/schemas/AgentsCursorList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentCatalogEntry"}}}}]},"ModelProvider":{"type":"object","additionalProperties":false,"description":"Write-only model credential. Omit it to run with the calling SandBase API key. Never returned.","properties":{"type":{"type":"string","enum":["sandbase","custom"],"default":"sandbase"},"base_url":{"type":"string","format":"uri","description":"Required for custom. HTTPS only, without credentials, query, or fragment. Not allowed for sandbase."},"api_key":{"type":"string","description":"Required for custom. Optional for sandbase, where it defaults to the calling key."}}},"SessionCreateRequest":{"type":"object","additionalProperties":false,"description":"Send agent_id, agent, or both.","anyOf":[{"required":["agent_id"]},{"required":["agent"]}],"properties":{"agent_id":{"type":"string","description":"Saved Agent ID (`agt_` prefix)."},"version":{"type":"integer","minimum":1,"description":"Agent version. Defaults to the current version. Not allowed with an inline Agent."},"title":{"type":"string","maxLength":512},"agent":{"type":"object","additionalProperties":false,"description":"Agent configuration, validated as in Create Agent. Without agent_id it defines an inline Agent and model is required; inline Agents carry no Skills or MCP connections. With agent_id, each field sent replaces that field of the saved version for this Session only.","properties":{"model":{"type":"string","maxLength":200},"instructions":{"type":["string","null"]},"runtime_profile":{"type":"string","enum":["codex","claude","mcode"],"description":"Defaults to codex for an inline Agent."},"service_tier":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object"}},"text":{"type":"object"},"reasoning":{"type":"object"},"multi_agent":{"type":"object"}}},"model":{"type":"string","maxLength":200,"description":"Model override for this Session. Must equal agent.model when both are sent."},"environment":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","const":"openai_hosted"}},"description":"OpenAI SDK compatibility only. Sessions always run in the SandBase hosted cloud, so omit this field in direct HTTP calls. The OpenAI SDK requires it; {\"type\":\"openai_hosted\"} is accepted and any other value returns 400."},"input":{"description":"Optional first input: a string, or an array with exactly one message, e.g. [{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"...\"}]}]. A bare object returns 400.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","const":"user"},"content":{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","const":"input_text"},"text":{"type":"string"}}}}}}}]},"metadata":{"type":"object","maxProperties":16,"additionalProperties":{"type":"string","maxLength":512}},"stream":{"type":"boolean","default":false,"description":"true requires a non-empty input and returns a 201 text/event-stream of the first turn."},"model_provider":{"$ref":"#/components/schemas/ModelProvider"}}},"SessionFailure":{"type":"object","required":["code","message","action"],"properties":{"code":{"type":"string","enum":["session_creation_rejected","execution_failed","model_authentication_failed","model_rate_limited","model_quota_exceeded","context_limit_exceeded","environment_connection_timeout","runtime_unavailable","model_request_failed","model_configuration_rejected","session_not_ready","session_execution_unavailable","session_configuration_unavailable","session_snapshot_unavailable"]},"message":{"type":"string"},"action":{"type":"string","description":"Suggested next step, such as retry_later, inspect_history, create_new_session, check_model_account, or create_session_with_updated_model_provider."},"retryable":{"type":"boolean"}}},"Session":{"type":"object","required":["id","object","agent","agent_id","agent_version","title","model","environment","metadata","status","lifecycle_status","sync_status","execution_status","failure","row_version","required_actions","vault_ids","created_at","last_active_at","updated_at","archived_at"],"properties":{"id":{"type":"string","description":"Session ID (`ses_` prefix)."},"object":{"type":"string","const":"agent.session"},"agent":{"type":"object","description":"OpenAI-shaped snapshot of the effective Agent configuration (id, name, model, instructions, multi_agent, reasoning, service_tier, text, tools)."},"agent_id":{"type":"string"},"agent_version":{"type":"integer"},"title":{"type":"string"},"model":{"type":"string"},"environment":{"type":"object","description":"Echo of the hosted execution context, kept for OpenAI SDK compatibility. It is not a Sandbox instance and needs no action from clients.","properties":{"id":{"type":"string"},"type":{"type":"string","const":"openai_hosted"},"skills":{"type":"array","items":{"type":"object"}}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"status":{"type":"string","enum":["idle","in_progress","requires_action","failed"],"description":"Execution status. requires_action is not supported yet and surfaces as a 502 executor_contract_error."},"lifecycle_status":{"type":"string","enum":["active","archived"]},"sync_status":{"type":"string"},"execution_status":{"type":"string"},"failure":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SessionFailure"}]},"row_version":{"type":"integer"},"required_actions":{"type":"array","items":{}},"vault_ids":{"type":"array","items":{"type":"string"}},"usage":{"type":["object","null"],"description":"Token usage; null until a turn reports usage."},"created_at":{"type":"integer"},"last_active_at":{"type":"integer"},"updated_at":{"type":"integer"},"archived_at":{"type":["integer","null"]},"source":{"type":["string","null"],"enum":["direct",null],"description":"direct for Sessions created with POST /v1/agents/sessions; null when the origin is unavailable (see source_failure_code)."},"source_id":{"type":["string","null"],"description":"Null for Sessions created directly with POST /v1/agents/sessions."},"source_failure_code":{"type":"string"}}},"SessionList":{"allOf":[{"$ref":"#/components/schemas/AgentsCursorList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}}}}]},"SessionUpdateRequest":{"type":"object","additionalProperties":false,"required":["metadata"],"properties":{"metadata":{"type":"object","maxProperties":16,"additionalProperties":{"type":"string","maxLength":512},"description":"Replaces the whole metadata map."}}},"SessionRenameRequest":{"type":"object","additionalProperties":false,"required":["title","row_version"],"properties":{"title":{"type":"string","maxLength":512},"row_version":{"type":"integer","minimum":1}}},"SessionRowVersionRequest":{"$ref":"#/components/schemas/RowVersionRequest"},"SessionEventsRequest":{"type":"object","additionalProperties":false,"description":"Either events (exactly one event) or the SandBase extension input/file_ids.","properties":{"events":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["agent.session.input.message","agent.session.input.cancel"]},"input":{"description":"For input.message: a string, or exactly one user message with one input_text part. Must be omitted for input.cancel."}}}},"input":{"type":"string","maxLength":262144,"description":"SandBase extension. Text input, non-empty."},"file_ids":{"type":"array","maxItems":10,"items":{"type":"string"},"description":"SandBase extension. Up to 10 distinct ready attachments."}}},"SessionDeleted":{"type":"object","required":["id","object","deleted"],"properties":{"id":{"type":"string"},"object":{"type":"string","const":"agent.session.deleted"},"deleted":{"type":"boolean","const":true}}},"SessionTurn":{"type":"object","additionalProperties":true,"required":["id"],"properties":{"id":{"type":"string"},"session_id":{"type":"string"},"agent_id":{"type":"string"},"status":{"type":"string"}}},"SessionCancelAccepted":{"type":"object","required":["session_id","accepted"],"properties":{"session_id":{"type":"string"},"accepted":{"type":"boolean","const":true}}},"SessionReconnect":{"type":"object","required":["session","stream_url","recovery","requires_authorization_header"],"properties":{"session":{"$ref":"#/components/schemas/Session"},"stream_url":{"type":"string","description":"Path of the product stream, for example /v1/agents/sessions/{session_id}/events/stream."},"recovery":{"type":"string","const":"snapshot_then_live"},"requires_authorization_header":{"type":"boolean","const":true}}},"SessionFileUpload":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Exactly one file part, up to 5 MiB. File names use letters, digits, spaces, dots, underscores, and hyphens (maximum 200 characters)."}}},"SessionFile":{"type":"object","required":["id","session_id","name","mime_type","size_bytes","status","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Attachment ID (`fil_` prefix)."},"session_id":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size_bytes":{"type":"integer"},"status":{"type":"string","enum":["pending","ready","failed","deleted"],"description":"Only ready attachments can be sent or downloaded."},"error_code":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SessionFileList":{"allOf":[{"$ref":"#/components/schemas/AgentsOffsetList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionFile"}}}}]},"SessionFileDeleted":{"type":"object","required":["deleted","id"],"properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string"}}},"SessionWorkspacePage":{"type":"object","required":["object","data","next","has_more"],"properties":{"object":{"type":"string","enum":["page"]},"data":{"type":"array","items":{"type":"object","required":["path","size_bytes"],"properties":{"path":{"type":"string"},"size_bytes":{"type":"integer","minimum":0}}}},"next":{"type":["string","null"]},"has_more":{"type":"boolean"}}},"SessionArtifact":{"type":"object","required":["object","id","session_id","path","size_bytes","created_at"],"properties":{"object":{"type":"string","enum":["agent.session.artifact"]},"id":{"type":"string","description":"Opaque art_ handle bound to this organization and Session."},"session_id":{"type":"string"},"path":{"type":"string","description":"Captured output path under /workspace/outputs/."},"size_bytes":{"type":"integer","minimum":0},"created_at":{"type":"integer","description":"Unix seconds."}}},"SessionArtifactList":{"type":"object","required":["object","data","has_more","first_id","last_id"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionArtifact"}},"has_more":{"type":"boolean"},"first_id":{"type":["string","null"]},"last_id":{"type":["string","null"]}}},"SecretCreateRequest":{"type":"object","additionalProperties":false,"required":["name","kind","server_url","token"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128},"kind":{"type":"string","const":"mcp_bearer"},"server_url":{"type":"string","format":"uri","maxLength":2048,"description":"HTTPS MCP server URL without credentials, query, or fragment. The Secret only works for this exact URL."},"token":{"type":"string","minLength":1,"maxLength":16384,"writeOnly":true}}},"SecretRotateRequest":{"type":"object","additionalProperties":false,"required":["token","row_version"],"properties":{"token":{"type":"string","minLength":1,"maxLength":16384,"writeOnly":true},"row_version":{"type":"integer","minimum":1}}},"Secret":{"type":"object","required":["id","name","kind","server_url","status","row_version","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Secret ID (`sec_` prefix)."},"name":{"type":"string"},"kind":{"type":"string","const":"mcp_bearer"},"server_url":{"type":"string"},"status":{"type":"string","enum":["pending","active","disabled"],"description":"disabled means revoked."},"row_version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SecretList":{"allOf":[{"$ref":"#/components/schemas/AgentsOffsetList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Secret"}}}}]},"MCPConnectionCreateRequest":{"type":"object","additionalProperties":false,"required":["name","server_url"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128},"server_url":{"type":"string","format":"uri","maxLength":2048,"description":"HTTPS URL without credentials, query, or fragment."},"secret_id":{"type":"string","description":"Optional active Secret for the same server_url. Omit for an anonymous server."}}},"MCPConnectionReplaceRequest":{"allOf":[{"$ref":"#/components/schemas/MCPConnectionCreateRequest"},{"type":"object","required":["row_version"],"properties":{"row_version":{"type":"integer","minimum":1}}}]},"MCPConnection":{"type":"object","required":["id","name","server_url","status","row_version","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Connection ID (`mcp_` prefix)."},"name":{"type":"string"},"server_url":{"type":"string"},"secret_id":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"row_version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"MCPConnectionList":{"allOf":[{"$ref":"#/components/schemas/AgentsOffsetList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MCPConnection"}}}}]},"SkillUploadForm":{"type":"object","required":["files"],"properties":{"files":{"type":"string","format":"binary","description":"Exactly one ZIP part named files (or files[]), up to 5 MiB, containing SKILL.md with name and description frontmatter."}}},"SkillVersionUploadForm":{"type":"object","required":["files"],"properties":{"files":{"type":"string","format":"binary","description":"Exactly one ZIP part, up to 5 MiB."},"default":{"type":"string","enum":["true","false"],"description":"Make this version the default."}}},"SkillUpdateRequest":{"type":"object","additionalProperties":false,"properties":{"default_version":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"metadata":{"type":["object","null"],"description":"Market metadata. Requires row_version; null or an empty object clears it."},"row_version":{"type":"integer","minimum":1}}},"Skill":{"type":"object","required":["id","object","name","description","default_version","latest_version","status","visibility","row_version","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Skill ID (`skl_` prefix)."},"object":{"type":"string","const":"skill"},"name":{"type":"string"},"description":{"type":"string"},"default_version":{"type":"string"},"latest_version":{"type":"string"},"status":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"row_version":{"type":"integer"},"metadata":{"type":"object"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"failure_code":{"type":"string"}}},"SkillList":{"allOf":[{"$ref":"#/components/schemas/AgentsCursorList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}}}}]},"SkillVersion":{"type":"object","required":["object","id","skill_id","version","name","description","created_at"],"properties":{"object":{"type":"string","const":"skill.version"},"id":{"type":"string","description":"<skill_id>:<version>"},"skill_id":{"type":"string"},"version":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"created_at":{"type":"integer"},"failure_code":{"type":"string"}}},"SkillVersionList":{"allOf":[{"$ref":"#/components/schemas/AgentsCursorList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkillVersion"}}}}]},"SkillDeleted":{"type":"object","required":["id","object","deleted"],"properties":{"id":{"type":"string"},"object":{"type":"string","const":"skill.deleted"},"deleted":{"type":"boolean","const":true}}}}}}