{ "openapi": "3.1.0", "info": { "title": "Bifrost API", "description": "Bifrost HTTP Transport API for AI model inference and gateway management.\n\nThis API provides a unified interface for interacting with multiple AI providers\nincluding OpenAI, Anthropic, Bedrock, Gemini, and more through a single API,\nalong with comprehensive management APIs for configuring and monitoring the gateway.\n\n## API Structure\n\n### Unified Inference API (`/v1/*`)\nThe primary API using Bifrost's unified format. Model parameters use the format\n`provider/model` (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`).\n\n### Async Inference API (`/v1/async/*`)\nSubmit inference requests for asynchronous execution. Returns a job ID immediately\nand allows polling for results. Supports all inference types except batches, files,\nand containers.\n\n### Provider Integration APIs\nNative provider-format APIs for drop-in compatibility:\n- `/openai/*` - OpenAI-compatible API\n- `/anthropic/*` - Anthropic-compatible API\n- `/genai/*` - Google GenAI (Gemini) compatible API\n- `/bedrock/*` - AWS Bedrock compatible API\n- `/cohere/*` - Cohere compatible API\n\n### Framework Integration APIs\nMulti-provider proxy endpoints for AI frameworks:\n- `/litellm/*` - LiteLLM proxy with all provider formats\n- `/langchain/*` - LangChain compatible endpoints\n- `/pydanticai/*` - PydanticAI compatible endpoints\n\n### Management APIs (`/api/*`)\nAPIs for managing and monitoring the Bifrost gateway:\n- `/api/config` - Configuration management\n- `/api/providers` - Provider and API key management\n- `/api/plugins` - Plugin management\n- `/api/governance/*` - Virtual keys, teams, customers, budgets, rate limits, routing rules, and pricing overrides\n- `/api/logs` - Log search and analytics\n- `/api/mcp/*` - MCP (Model Context Protocol) client management\n- `/api/session/*` - Authentication and session management\n- `/api/cache/*` - Cache management\n- `/health` - Health check endpoint\n\n## Fallbacks\nRequests can include fallback models that will be tried if the primary model fails.\n", "version": "1.0.0", "contact": { "name": "Contact Us", "url": "https://getmaxim.ai/bifrost" }, "license": { "name": "Apache 2.0", "url": "https://opensource.org/licenses/Apache-2.0" } }, "servers": [ { "url": "{baseUrl}", "description": "Your Bifrost instance", "variables": { "baseUrl": { "default": "http://localhost:8080", "description": "Base URL of your Bifrost instance (e.g. https://bifrost.mycompany.com)" } } } ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "ApiKeyAuth": [] } ], "tags": [ { "name": "Models", "description": "Model listing and information" }, { "name": "Chat Completions", "description": "Chat-based text generation" }, { "name": "Text Completions", "description": "Text completion generation" }, { "name": "Responses", "description": "OpenAI Responses API compatible endpoints" }, { "name": "OCR", "description": "Optical character recognition for documents and images" }, { "name": "Rerank", "description": "Document reranking by relevance to a query" }, { "name": "Embeddings", "description": "Text embedding generation" }, { "name": "Images", "description": "Image generations, editing, and variations" }, { "name": "Videos", "description": "Video generation and management" }, { "name": "Audio", "description": "Speech synthesis and transcription" }, { "name": "Count Tokens", "description": "Token counting utilities" }, { "name": "Batch", "description": "Batch processing operations" }, { "name": "Files", "description": "File management operations" }, { "name": "Containers", "description": "Container management operations" }, { "name": "Async Jobs", "description": "Asynchronous job submission and retrieval endpoints" }, { "name": "Realtime", "description": "Realtime WebSocket and WebRTC endpoints" }, { "name": "OpenAI Integration", "description": "OpenAI-compatible API endpoints (/openai/*)" }, { "name": "Azure Integration", "description": "Azure OpenAI integration endpoints" }, { "name": "Anthropic Integration", "description": "Anthropic-compatible API endpoints (/anthropic/*)" }, { "name": "GenAI Integration", "description": "Google GenAI (Gemini) compatible API endpoints (/genai/*)" }, { "name": "Bedrock Integration", "description": "AWS Bedrock compatible API endpoints (/bedrock/*)" }, { "name": "Cohere Integration", "description": "Cohere compatible API endpoints (/cohere/*)" }, { "name": "LiteLLM Integration", "description": "LiteLLM proxy endpoints with multi-provider support (/litellm/*)" }, { "name": "LangChain Integration", "description": "LangChain compatible endpoints with multi-provider support (/langchain/*)" }, { "name": "PydanticAI Integration", "description": "PydanticAI compatible endpoints with multi-provider support (/pydanticai/*)" }, { "name": "Health", "description": "Health check endpoints" }, { "name": "Configuration", "description": "Configuration management endpoints" }, { "name": "Session", "description": "Session and authentication endpoints" }, { "name": "Providers", "description": "Provider management endpoints" }, { "name": "Plugins", "description": "Plugin management endpoints" }, { "name": "MCP", "description": "Model Context Protocol endpoints" }, { "name": "Governance", "description": "Virtual keys, teams, and customers management" }, { "name": "Routing", "description": "Routing rules and complexity analyzer configuration" }, { "name": "Logging", "description": "Log search and management endpoints" }, { "name": "Cache", "description": "Cache management endpoints" }, { "name": "Vault", "description": "Vault secret management endpoints" }, { "name": "Skills", "description": "Skills Repository management, marketplace, and download endpoints" }, { "name": "Audit Logs", "description": "CADF-compliant audit log search, export, and signature verification endpoints" }, { "name": "Webhooks", "description": "Webhook endpoint management and signed async-job delivery history" }, { "name": "Notifications", "description": "Role-targeted dashboard notifications, delivered over the dashboard WebSocket" } ], "paths": { "/v1/models": { "get": { "operationId": "listModels", "summary": "List available models", "description": "Lists available models. If provider is not specified, lists all models from all configured providers.\n\nIf a virtual key is provided, Bifrost only lists (and only queries) providers allowed by that virtual key.\n", "tags": [ "Models" ], "parameters": [ { "name": "provider", "in": "query", "description": "Filter by provider (e.g., openai, anthropic, bedrock)", "schema": { "$ref": "#/components/schemas/ModelProvider" } }, { "name": "page_size", "in": "query", "description": "Maximum number of models to return", "schema": { "type": "integer", "minimum": 0 } }, { "name": "page_token", "in": "query", "description": "Token for pagination", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/chat/completions": { "post": { "operationId": "createChatCompletion", "summary": "Create a chat completion", "description": "Creates a completion for the provided messages. Supports streaming via SSE.\n", "tags": [ "Chat Completions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming chat completion response (SSE format)", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "created": { "type": "integer" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/completions": { "post": { "operationId": "createTextCompletion", "summary": "Create a text completion", "description": "Creates a completion for the provided prompt. Supports streaming via SSE.\n", "tags": [ "Text Completions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming text completion response", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/responses": { "post": { "operationId": "createResponse", "summary": "Create a response", "description": "Creates a response using the OpenAI Responses API format. Supports streaming via SSE.\n", "tags": [ "Responses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming responses API response (SSE format)", "properties": { "type": { "type": "string", "enum": [ "response.ping", "response.created", "response.in_progress", "response.completed", "response.failed", "response.incomplete", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.refusal.delta", "response.refusal.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.results.added", "response.file_search_call.results.completed", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.web_search_call.results.added", "response.web_search_call.results.completed", "response.web_fetch_call.in_progress", "response.web_fetch_call.fetching", "response.web_fetch_call.completed", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.image_generation_call.completed", "response.image_generation_call.generating", "response.image_generation_call.in_progress", "response.image_generation_call.partial_image", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.mcp_call.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_list_tools.in_progress", "response.code_interpreter_call.in_progress", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.output_text.annotation.added", "response.output_text.annotation.done", "response.queued", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "error" ] }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "output_index": { "type": "integer" }, "item": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "content_index": { "type": "integer" }, "item_id": { "type": "string" }, "part": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "delta": { "type": "string" }, "signature": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "text": { "type": "string" }, "refusal": { "type": "string" }, "arguments": { "type": "string" }, "partial_image_b64": { "type": "string" }, "partial_image_index": { "type": "integer" }, "annotation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } }, "annotation_index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "createResponseWebSocket", "summary": "Responses API over WebSocket", "description": "Upgrades the connection to a WebSocket and runs the OpenAI Responses API\nin WebSocket Mode. Clients send `response.create` events on the socket and\nreceive streamed events through the standard inference pipeline (PreLLMHook,\nkey selection, provider call, PostLLMHook).\n\nAuth is identical to the HTTP POST variant — Bearer/Basic/Virtual Key/API Key\nmay be supplied as request headers on the upgrade request. The OpenAI SDK can\nalso pass an API key via the `openai-insecure-api-key.` WebSocket\nsubprotocol.\n\nThis GET endpoint shares its path with the POST inference endpoint; route\nselection is based on the `Upgrade: websocket` request header.\n", "tags": [ "Responses" ], "parameters": [ { "name": "Upgrade", "in": "header", "required": true, "description": "Must be `websocket`", "schema": { "type": "string", "enum": [ "websocket" ] } }, { "name": "Sec-WebSocket-Protocol", "in": "header", "required": false, "description": "Optional WebSocket subprotocol. Use `openai-insecure-api-key.` to\nauthenticate when headers cannot be supplied by the client.\n", "schema": { "type": "string" } } ], "responses": { "101": { "description": "Switching Protocols — WebSocket upgrade succeeded" }, "401": { "description": "Authentication failed" }, "429": { "description": "Maximum concurrent WebSocket connections reached" } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/ocr": { "post": { "operationId": "performOCR", "summary": "Perform OCR", "description": "Extracts text and content from documents or images using optical character recognition.\nSupports PDF URLs, base64-encoded documents, and image URLs.\n", "tags": [ "OCR" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCRRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCRResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/rerank": { "post": { "operationId": "rerankDocuments", "summary": "Rerank documents", "description": "Reorders input documents by relevance to a query.\n", "tags": [ "Rerank" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/embeddings": { "post": { "operationId": "createEmbedding", "summary": "Create embeddings", "description": "Creates an embedding vector representing the input text.\n", "tags": [ "Embeddings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/audio/speech": { "post": { "operationId": "createSpeech", "summary": "Create speech", "description": "Generates audio from the input text. Returns audio data or streams via SSE.\n", "tags": [ "Audio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SpeechResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "speech.audio.delta", "speech.audio.done" ] }, "audio": { "type": "string", "format": "byte" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/audio/transcriptions": { "post": { "operationId": "createTranscription", "summary": "Create transcription", "description": "Transcribes audio into text in the input language.\n", "tags": [ "Audio" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TranscriptionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transcript.text.delta", "transcript.text.done" ] }, "delta": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" } } } } }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tokens", "duration" ] }, "input_tokens": { "type": "integer" }, "input_token_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "seconds": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/images/generations": { "post": { "operationId": "imageGeneration", "summary": "Generate an image", "description": "Generates images from text prompts using the specified model.\n", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "prompt": { "type": "string", "description": "Text prompt to generate image" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of images to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the generated image" }, "quality": { "type": "string", "enum": [ "auto", "high", "medium", "low", "hd", "standard" ], "description": "Quality of the generated image" }, "style": { "type": "string", "enum": [ "natural", "vivid" ], "description": "Style of the generated image" }, "response_format": { "type": "string", "enum": [ "url", "b64_json", "data_uri" ], "default": "url", "description": "Format of the response. `data_uri` is supported by providers that return an inline\ndata URI (e.g. Runware).\n" }, "input_images": { "type": "array", "items": { "type": "string" }, "description": "Input images for image-to-image generation, as public URLs, provider-side asset IDs,\nor base64 data URIs. Providers that accept only a single input use the first entry.\n" }, "aspect_ratio": { "type": "string", "description": "Aspect ratio of the generated image (e.g. `16:9`), for providers that accept one in place of `size`" }, "type": { "type": "string", "description": "Operation selector for providers that expose more than one generation task\n(e.g. `vectorize` for text-to-SVG on Runware). Omit for standard generation.\n" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Background type for the image" }, "moderation": { "type": "string", "enum": [ "low", "auto" ], "description": "Content moderation level" }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Number of partial images to generate" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression level (0-100%)" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg", "tiff", "svg" ], "description": "Output image format. `svg` applies to vectorize operations" }, "user": { "type": "string", "description": "User identifier for tracking" }, "seed": { "type": "integer", "description": "Seed for reproducible image generation" }, "negative_prompt": { "type": "string", "description": "Negative prompt to guide what to avoid in generation" }, "num_inference_steps": { "type": "integer", "description": "Number of inference steps for generation" }, "stream": { "type": "boolean", "default": false, "description": "Whether to stream the response. When true, images are sent as SSE.\nWhen streaming, providers may return base64 chunks (`b64_json`) and/or URLs (`url`) depending on provider and configuration.\n" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } ] } } } }, "responses": { "200": { "description": "Successful response. Returns JSON for non-streaming requests, or Server-Sent Events (SSE) stream when `stream=true`.\nWhen streaming, events are sent with the following event types:\n- `image_generation.partial_image`: Intermediate image chunks with base64-encoded image data\n- `image_generation.completed`: Final event for each image with usage information\n- `error`: Error events with error details\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the generation request" }, "created": { "type": "integer", "format": "int64", "description": "Unix timestamp when the image was created" }, "model": { "type": "string", "description": "Model used for generation" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-side asset identifier, when one is assigned. Providers that accept their own\nasset IDs as inputs (e.g. Runware) allow this to be fed straight into a follow-up task.\n" }, "url": { "type": "string", "format": "uri", "description": "URL of the generated image" }, "b64_json": { "type": "string", "description": "Base64-encoded image data" }, "revised_prompt": { "type": "string", "description": "Revised prompt used for generation" }, "index": { "type": "integer", "description": "Index of this image" }, "detections": { "type": "array", "items": { "type": "object", "description": "A region located by a masking model, in absolute input-image pixels", "properties": { "x_min": { "type": "integer" }, "y_min": { "type": "integer" }, "x_max": { "type": "integer" }, "y_max": { "type": "integer" } } }, "description": "Regions located by a masking or segmentation operation" } } }, "description": "Array of generated images" }, "background": { "type": "string", "description": "Background type for the image" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg" ], "description": "Output image format" }, "quality": { "type": "string", "description": "Quality of the generated image" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the generated image" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming response chunk for image generation.\nSent via Server-Sent Events (SSE).\nProviders may return either b64_json (base64-encoded image data) or url (public URL to the image).\n", "properties": { "id": { "type": "string", "description": "Request identifier" }, "type": { "type": "string", "enum": [ "image_generation.partial_image", "image_generation.completed", "error" ], "description": "Type of stream event" }, "partial_image_index": { "type": "integer", "description": "Index of the partial image chunk" }, "sequence_number": { "type": "integer", "description": "Sequence number for event ordering within the stream" }, "b64_json": { "type": "string", "description": "Base64-encoded chunk of image data.\nOptional; either b64_json or url may be present.\n" }, "url": { "type": "string", "format": "uri", "description": "Optional public URL to the generated image chunk.\nUsed by HuggingFace and other providers that return image URLs instead of base64 data.\n" }, "created_at": { "type": "integer", "format": "int64", "description": "Timestamp when chunk was created" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the generated image" }, "quality": { "type": "string", "description": "Quality setting used" }, "background": { "type": "string", "description": "Background type used" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg" ], "description": "Output format used" }, "revised_prompt": { "type": "string", "description": "Revised prompt" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } }, "description": "Token usage" }, "error": { "$ref": "#/components/schemas/BifrostError", "description": "Error information if generation failed" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/images/edits": { "post": { "operationId": "imageEdit", "summary": "Edit an image", "description": "Edits an image using a text prompt and optional mask. Accepts either `application/json` (sources\nas URLs or base64 under `images`) or `multipart/form-data` (to upload the image as `image` or\n`image[]`). Requires at least `model`, one image, and `prompt` - the latter except for the\noperation types driven purely by the input image, e.g. `background_removal`. Only the JSON body\npreserves the types of provider-native extra params; multipart carries every value as a string.\n", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON encoding of an image edit. Sources are supplied as an `images` array, the same nested form\n/v1/videos/edits uses for its source video. Unrecognised top-level fields are forwarded to the\nprovider as extra params with their JSON types intact, which is what a model's nested tuning\nobject needs (e.g. Runware's `settings` and `providerSettings`). To upload the image as a file,\npost `multipart/form-data` instead - see `ImageEditMultipartRequest`.\n", "required": [ "model", "images" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "images": { "type": "array", "items": { "description": "One source image, either as a bare string - the form `input_images` takes on\n/v1/images/generations - or as an object naming which arm it fills. Providers that cannot accept\na given form reject it.\n", "oneOf": [ { "type": "string", "description": "Public URL, data URI, base64 payload, or provider-side asset ID. Equivalent to the object\nform's `url`.\n" }, { "type": "object", "description": "Exactly one of the two properties is expected.", "properties": { "url": { "type": "string", "description": "Public URL, data URI, or provider-side asset ID, for providers whose upstream fetches\nthe asset itself (e.g. Runware). Avoids round-tripping the asset through the gateway as\nbase64.\n" }, "image": { "type": "string", "format": "byte", "description": "Base64-encoded image bytes" } } } ] }, "description": "Source images. Entries carrying neither a URL nor bytes are dropped; a request left with no\nusable image is rejected. Providers treat the first image as the primary one (Runware's seed\nimage, Bedrock's style-transfer base), so the order is part of the contract. Only the\nreference-image models accept more than one; elsewhere images after the first are dropped.\n" }, "prompt": { "type": "string", "description": "Text prompt describing the edit. Required except for the operation types that are driven\npurely by the input image: `background_removal`, `erase_object`, `upscale`, `upscale_fast`,\n`mask`, `segmentation`, `vectorize` and `controlnet_preprocess`.\n" }, "mask": { "type": "string", "format": "byte", "description": "Optional base64-encoded mask image for inpainting (transparent areas indicate regions to\nedit). Dropped for models that declare no mask input.\n" }, "type": { "type": "string", "enum": [ "inpainting", "outpainting", "background_removal", "remove_background", "remove_bg", "erase_object", "recolor", "search_replace", "control_sketch", "control_structure", "style_guide", "style_transfer", "upscale", "upscale_fast", "upscale_creative", "upscale_conservative", "mask", "segmentation", "vectorize", "controlnet_preprocess", "controlnet", "preprocess" ], "description": "Type of edit operation. Support varies by provider; unsupported values are dropped and the\nrequest runs as a standard edit.\n" }, "upscale_factor": { "type": "integer", "description": "Multiply each dimension by this factor. `type: \"upscale\"` only; mutually exclusive with\n`target_megapixels`.\n" }, "target_megapixels": { "type": "integer", "description": "Target output size in megapixels. `type: \"upscale\"` only; mutually exclusive with\n`upscale_factor`.\n" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of images to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "auto" ], "description": "Size of the output image" }, "response_format": { "type": "string", "enum": [ "url", "b64_json", "data_uri" ], "default": "url", "description": "Format of the response. `data_uri` is supported by providers that return an inline\ndata URI (e.g. Runware).\n" }, "stream": { "type": "boolean", "default": false, "description": "When true, stream the response via Server-Sent Events" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Background type for the image" }, "input_fidelity": { "type": "string", "enum": [ "low", "high" ], "description": "How closely to follow the original image" }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Number of partial images to generate when streaming" }, "quality": { "type": "string", "enum": [ "auto", "high", "medium", "low", "standard" ], "description": "Quality of the output image" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg", "tiff", "svg" ], "description": "Output image format. `svg` applies to vectorize operations" }, "num_inference_steps": { "type": "integer", "description": "Number of inference steps" }, "seed": { "type": "integer", "description": "Seed for reproducible editing" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression level (0-100%)" }, "negative_prompt": { "type": "string", "description": "What to avoid in the edit" }, "user": { "type": "string", "description": "User identifier for tracking" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } }, "multipart/form-data": { "schema": { "type": "object", "description": "Multipart encoding of an image edit, and the only encoding that can upload the image as a file.\nThis is what the official OpenAI SDKs send unconditionally. Every value crosses the wire as a\nstring, so provider-native extra params arrive as strings; post `application/json` instead when\na provider expects them as numbers, booleans or nested objects - see `ImageEditRequest`.\n", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "prompt": { "type": "string", "description": "Text prompt describing the edit. Required except for the operation types that are driven\npurely by the input image: `background_removal`, `erase_object`, `upscale`, `upscale_fast`,\n`mask`, `segmentation`, `vectorize` and `controlnet_preprocess`.\n" }, "image": { "type": "string", "format": "binary", "description": "Image file to edit. Use field name `image` for a single file or `image[]` for multiple files.\nEither `image` or `image_url` is required.\n" }, "image_url": { "type": "string", "description": "Input image as a public URL or provider-side asset ID, for providers whose upstream fetches\nthe asset itself (e.g. Runware). Use `image_url` for one or `image_url[]` for several; this\navoids round-tripping the asset through the gateway as base64. Uploads keep their leading\nposition, and providers treat the first image as the primary one.\n" }, "mask": { "type": "string", "format": "binary", "description": "Optional mask image for inpainting (transparent areas indicate regions to edit). Dropped for\nmodels that declare no mask input.\n" }, "type": { "type": "string", "enum": [ "inpainting", "outpainting", "background_removal", "remove_background", "remove_bg", "erase_object", "recolor", "search_replace", "control_sketch", "control_structure", "style_guide", "style_transfer", "upscale", "upscale_fast", "upscale_creative", "upscale_conservative", "mask", "segmentation", "vectorize", "controlnet_preprocess", "controlnet", "preprocess" ], "description": "Type of edit operation. Support varies by provider; unsupported values are dropped and the\nrequest runs as a standard edit.\n" }, "upscale_factor": { "type": "integer", "description": "Multiply each dimension by this factor. `type: \"upscale\"` only; mutually exclusive with\n`target_megapixels`.\n" }, "target_megapixels": { "type": "integer", "description": "Target output size in megapixels. `type: \"upscale\"` only; mutually exclusive with\n`upscale_factor`.\n" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of images to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "auto" ], "description": "Size of the output image" }, "response_format": { "type": "string", "enum": [ "url", "b64_json", "data_uri" ], "default": "url", "description": "Format of the response. `data_uri` is supported by providers that return an inline\ndata URI (e.g. Runware).\n" }, "stream": { "type": "boolean", "default": false, "description": "When true, stream the response via Server-Sent Events" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Background type for the image" }, "input_fidelity": { "type": "string", "enum": [ "low", "high" ], "description": "How closely to follow the original image" }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Number of partial images to generate when streaming" }, "quality": { "type": "string", "enum": [ "auto", "high", "medium", "low", "standard" ], "description": "Quality of the output image" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg", "tiff", "svg" ], "description": "Output image format. `svg` applies to vectorize operations" }, "num_inference_steps": { "type": "integer", "description": "Number of inference steps" }, "seed": { "type": "integer", "description": "Seed for reproducible editing" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression level (0-100%)" }, "negative_prompt": { "type": "string", "description": "What to avoid in the edit" }, "user": { "type": "string", "description": "User identifier for tracking" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } } } }, "responses": { "200": { "description": "Successful response. Returns JSON for non-streaming requests, or Server-Sent Events (SSE) stream when `stream=true`.\nWhen streaming, events are sent with the following event types:\n- `image_edit.partial_image`: Intermediate image chunks with base64-encoded image data\n- `image_edit.completed`: Final event for each image with usage information\n- `error`: Error events with error details\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the generation request" }, "created": { "type": "integer", "format": "int64", "description": "Unix timestamp when the image was created" }, "model": { "type": "string", "description": "Model used for generation" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-side asset identifier, when one is assigned. Providers that accept their own\nasset IDs as inputs (e.g. Runware) allow this to be fed straight into a follow-up task.\n" }, "url": { "type": "string", "format": "uri", "description": "URL of the generated image" }, "b64_json": { "type": "string", "description": "Base64-encoded image data" }, "revised_prompt": { "type": "string", "description": "Revised prompt used for generation" }, "index": { "type": "integer", "description": "Index of this image" }, "detections": { "type": "array", "items": { "type": "object", "description": "A region located by a masking model, in absolute input-image pixels", "properties": { "x_min": { "type": "integer" }, "y_min": { "type": "integer" }, "x_max": { "type": "integer" }, "y_max": { "type": "integer" } } }, "description": "Regions located by a masking or segmentation operation" } } }, "description": "Array of generated images" }, "background": { "type": "string", "description": "Background type for the image" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg" ], "description": "Output image format" }, "quality": { "type": "string", "description": "Quality of the generated image" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the generated image" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming response chunk for image edit.\nSent via Server-Sent Events (SSE) when `stream=true`.\n", "properties": { "id": { "type": "string", "description": "Request identifier" }, "type": { "type": "string", "enum": [ "image_edit.partial_image", "image_edit.completed", "error" ], "description": "Type of stream event" }, "partial_image_index": { "type": "integer", "description": "Index of the partial image chunk" }, "sequence_number": { "type": "integer", "description": "Sequence number for event ordering within the stream" }, "b64_json": { "type": "string", "description": "Base64-encoded chunk of image data; optional" }, "url": { "type": "string", "format": "uri", "description": "Optional public URL to the image chunk" }, "created_at": { "type": "integer", "format": "int64", "description": "Timestamp when chunk was created" }, "size": { "type": "string", "description": "Size of the image" }, "quality": { "type": "string", "description": "Quality setting used" }, "background": { "type": "string", "description": "Background type used" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg" ], "description": "Output format used" }, "revised_prompt": { "type": "string", "description": "Revised prompt" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } }, "description": "Token usage" }, "error": { "$ref": "#/components/schemas/BifrostError", "description": "Error information if edit failed" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/images/variations": { "post": { "operationId": "imageVariation", "summary": "Create Variation", "description": "Creates variations of an image. Request must be sent as multipart/form-data with `model` and `image` (or `image[]`).\nDoes not support streaming.\n", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "model", "image" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "image": { "type": "string", "format": "binary", "description": "Image file to create variations of. Use field name `image` for a single file or `image[]` for multiple (first image is used).\n" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of variations to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the output images" }, "response_format": { "type": "string", "enum": [ "url", "b64_json" ], "default": "url", "description": "Format of the response" }, "user": { "type": "string", "description": "User identifier for tracking" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } } } }, "responses": { "200": { "description": "Successful response. Returns JSON with generated image variation(s).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the generation request" }, "created": { "type": "integer", "format": "int64", "description": "Unix timestamp when the image was created" }, "model": { "type": "string", "description": "Model used for generation" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-side asset identifier, when one is assigned. Providers that accept their own\nasset IDs as inputs (e.g. Runware) allow this to be fed straight into a follow-up task.\n" }, "url": { "type": "string", "format": "uri", "description": "URL of the generated image" }, "b64_json": { "type": "string", "description": "Base64-encoded image data" }, "revised_prompt": { "type": "string", "description": "Revised prompt used for generation" }, "index": { "type": "integer", "description": "Index of this image" }, "detections": { "type": "array", "items": { "type": "object", "description": "A region located by a masking model, in absolute input-image pixels", "properties": { "x_min": { "type": "integer" }, "y_min": { "type": "integer" }, "x_max": { "type": "integer" }, "y_max": { "type": "integer" } } }, "description": "Regions located by a masking or segmentation operation" } } }, "description": "Array of generated images" }, "background": { "type": "string", "description": "Background type for the image" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg" ], "description": "Output image format" }, "quality": { "type": "string", "description": "Quality of the generated image" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the generated image" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/videos": { "post": { "operationId": "videoGeneration", "summary": "Generate a video", "description": "Creates a video generation job from a text prompt. This is an asynchronous operation\nthat returns immediately with a job ID. Use the retrieve endpoint to check the status\nand get the video URL when generation is complete.\n", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "prompt": { "type": "string", "description": "Text prompt describing the video to generate. Optional for operations driven purely by an\ninput asset, such as image-to-3D.\n" }, "type": { "type": "string", "enum": [ "3d", "upscale", "background_removal", "remove_background", "remove_bg" ], "description": "Operation selector for providers that run more than one async task type on this endpoint\n(e.g. `3d` for mesh generation on Runware). Omit for standard video generation.\n" }, "output_format": { "type": "string", "enum": [ "mp4", "webm", "mov" ], "description": "Output container format" }, "input_reference": { "type": "string", "description": "Optional reference image for image-to-video. OpenAI and Gemini require a base64 data URL (e.g., `data:image/png;base64,...`). Runway and Replicate accept both data URLs and plain URLs." }, "seconds": { "type": "string", "description": "Duration of the video in seconds as a string (e.g., \"4\")" }, "size": { "type": "string", "description": "Resolution of the generated video (e.g., `1280x720`, `720x1280`, `1920x1080`)" }, "negative_prompt": { "type": "string", "description": "Text describing what to avoid in the generated video" }, "seed": { "type": "integer", "description": "Seed for reproducible generation" }, "video_uri": { "type": "string", "description": "Source video URI for video-to-video generation (provider-specific, e.g. GCS URI)" }, "audio": { "type": "boolean", "description": "Enable audio generation in the video (supported by select providers/models)" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } } } }, "responses": { "200": { "description": "Successful response. Returns a video generation job object with status information.\nPoll the retrieve endpoint to check completion status.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-native job ID. To use in path parameters (retrieve/delete/download), combine as `{id}:{provider}` (e.g., `task_abc123:runway`)" }, "object": { "type": "string", "enum": [ "video" ], "description": "Object type, always \"video\"" }, "model": { "type": "string", "description": "Model used for video generation" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ], "description": "Current lifecycle status of the video generation job:\n- `queued`: Job is waiting to be processed\n- `in_progress`: Video is currently being generated\n- `completed`: Video generation completed successfully\n- `failed`: Video generation failed\n" }, "progress": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Approximate completion percentage (0-100)" }, "prompt": { "type": "string", "description": "Prompt used to generate the video" }, "remixed_from_video_id": { "type": "string", "description": "Source video ID if this is a remix" }, "seconds": { "type": "string", "description": "Duration of the generated video in seconds as a string (e.g., \"4\")" }, "size": { "type": "string", "description": "Resolution of the generated video (e.g., \"1920x1080\")" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job was created" }, "completed_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job completed" }, "expires_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when downloadable assets expire" }, "videos": { "type": "array", "description": "Generated video outputs (only present when status is \"completed\")", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url", "base64" ], "description": "Output format of this video" }, "url": { "type": "string", "format": "uri", "description": "URL to the generated video (present when type is \"url\")" }, "base64": { "type": "string", "description": "Base64-encoded video content (present when type is \"base64\")" }, "content_type": { "type": "string", "description": "MIME type of the video (e.g., \"video/mp4\")" } } } }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Human-readable error message" } } }, "content_filter": { "type": "object", "description": "Information about content that was filtered due to safety policies", "properties": { "filtered_count": { "type": "integer", "description": "Number of items filtered" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Human-readable reasons for filtering" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "videoList", "summary": "List video generation jobs", "description": "Lists video generation jobs for a specific provider. Results are paginated\nand can be filtered using query parameters.\n", "tags": [ "Videos" ], "parameters": [ { "name": "provider", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Provider name (e.g., \"openai\", \"gemini\")" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for pagination - ID of the last item from the previous page" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of results to return" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order by creation time" } ], "responses": { "200": { "description": "Successful response. Returns a paginated list of video generation jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type, always \"list\"" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-native video ID. To use in path parameters (retrieve/delete/download), combine as `{id}:{provider}` (e.g., `task_abc123:runway`)" }, "object": { "type": "string", "enum": [ "video" ], "description": "Object type, always \"video\"" }, "model": { "type": "string", "description": "Model used for generation" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ], "description": "Current lifecycle status of the video generation job:\n- `queued`: Job is waiting to be processed\n- `in_progress`: Video is currently being generated\n- `completed`: Video generation completed successfully\n- `failed`: Video generation failed\n" }, "progress": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Approximate completion percentage (0-100)" }, "prompt": { "type": "string", "description": "Prompt used to generate the video" }, "remixed_from_video_id": { "type": "string", "description": "Source video ID if this is a remix" }, "seconds": { "type": "string", "description": "Duration of the video in seconds as a string (e.g., \"4\")" }, "size": { "type": "string", "description": "Resolution of the generated video (e.g., \"1920x1080\")" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job was created" }, "completed_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job completed" }, "expires_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when downloadable assets expire" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Human-readable error message" } } } } }, "description": "Array of video generation jobs" }, "first_id": { "type": "string", "description": "ID of the first item in the list" }, "last_id": { "type": "string", "description": "ID of the last item in the list" }, "has_more": { "type": "boolean", "description": "Whether there are more results available" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/videos/{video_id}": { "get": { "operationId": "videoRetrieve", "summary": "Retrieve a video generation job", "description": "Retrieves the status and metadata for a video generation job.\nUse this endpoint to poll for completion status after creating a video generation job.\nWhen the status is \"completed\", the response will include a URL to download the video.\n", "tags": [ "Videos" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Video ID in format `id:provider` (e.g., `video_abc123:openai`)" } ], "responses": { "200": { "description": "Successful response. Returns the video generation job details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-native job ID. To use in path parameters (retrieve/delete/download), combine as `{id}:{provider}` (e.g., `task_abc123:runway`)" }, "object": { "type": "string", "enum": [ "video" ], "description": "Object type, always \"video\"" }, "model": { "type": "string", "description": "Model used for video generation" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ], "description": "Current lifecycle status of the video generation job:\n- `queued`: Job is waiting to be processed\n- `in_progress`: Video is currently being generated\n- `completed`: Video generation completed successfully\n- `failed`: Video generation failed\n" }, "progress": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Approximate completion percentage (0-100)" }, "prompt": { "type": "string", "description": "Prompt used to generate the video" }, "remixed_from_video_id": { "type": "string", "description": "Source video ID if this is a remix" }, "seconds": { "type": "string", "description": "Duration of the generated video in seconds as a string (e.g., \"4\")" }, "size": { "type": "string", "description": "Resolution of the generated video (e.g., \"1920x1080\")" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job was created" }, "completed_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job completed" }, "expires_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when downloadable assets expire" }, "videos": { "type": "array", "description": "Generated video outputs (only present when status is \"completed\")", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url", "base64" ], "description": "Output format of this video" }, "url": { "type": "string", "format": "uri", "description": "URL to the generated video (present when type is \"url\")" }, "base64": { "type": "string", "description": "Base64-encoded video content (present when type is \"base64\")" }, "content_type": { "type": "string", "description": "MIME type of the video (e.g., \"video/mp4\")" } } } }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Human-readable error message" } } }, "content_filter": { "type": "object", "description": "Information about content that was filtered due to safety policies", "properties": { "filtered_count": { "type": "integer", "description": "Number of items filtered" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Human-readable reasons for filtering" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Video not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "videoDelete", "summary": "Delete a video generation job", "description": "Deletes a video generation job and its associated assets.\nThis operation cannot be undone.\n", "tags": [ "Videos" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Video ID in format `id:provider` (e.g., `video_abc123:openai`)" } ], "responses": { "200": { "description": "Successful response. Returns deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted video" }, "object": { "type": "string", "enum": [ "video.deleted" ], "description": "Object type, always \"video.deleted\"" }, "deleted": { "type": "boolean", "description": "Whether the video was successfully deleted" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Video not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/videos/{video_id}/content": { "get": { "operationId": "videoDownload", "summary": "Download video content", "description": "Downloads the binary content of a generated video.\nThe video must have a status of \"completed\" to be downloadable.\nReturns the raw video file (typically MP4 format).\n", "tags": [ "Videos" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Video ID in format `id:provider` (e.g., `video_abc123:openai`)" }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "video", "thumbnail", "spritesheet" ] }, "description": "Variant of the video content to download (provider-specific)" } ], "responses": { "200": { "description": "Successful response. Returns the video file as binary content.", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Video not found or not yet available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/videos/{video_id}/remix": { "post": { "operationId": "videoRemix", "summary": "Remix a video", "description": "Creates a new video generation job by remixing an existing video with a new prompt.\nThe source video must have a status of \"completed\" to be remixed.\nReturns a new video generation job that can be polled for completion.\n", "tags": [ "Videos" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Video ID in format `id:provider` (e.g., `video_abc123:openai`)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Text prompt describing how to remix the video" } } } } } }, "responses": { "200": { "description": "Successful response. Returns a new video generation job object.\nPoll the retrieve endpoint to check completion status.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-native job ID. To use in path parameters (retrieve/delete/download), combine as `{id}:{provider}` (e.g., `task_abc123:runway`)" }, "object": { "type": "string", "enum": [ "video" ], "description": "Object type, always \"video\"" }, "model": { "type": "string", "description": "Model used for video generation" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ], "description": "Current lifecycle status of the video generation job:\n- `queued`: Job is waiting to be processed\n- `in_progress`: Video is currently being generated\n- `completed`: Video generation completed successfully\n- `failed`: Video generation failed\n" }, "progress": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Approximate completion percentage (0-100)" }, "prompt": { "type": "string", "description": "Prompt used to generate the video" }, "remixed_from_video_id": { "type": "string", "description": "Source video ID if this is a remix" }, "seconds": { "type": "string", "description": "Duration of the generated video in seconds as a string (e.g., \"4\")" }, "size": { "type": "string", "description": "Resolution of the generated video (e.g., \"1920x1080\")" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job was created" }, "completed_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job completed" }, "expires_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when downloadable assets expire" }, "videos": { "type": "array", "description": "Generated video outputs (only present when status is \"completed\")", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url", "base64" ], "description": "Output format of this video" }, "url": { "type": "string", "format": "uri", "description": "URL to the generated video (present when type is \"url\")" }, "base64": { "type": "string", "description": "Base64-encoded video content (present when type is \"base64\")" }, "content_type": { "type": "string", "description": "MIME type of the video (e.g., \"video/mp4\")" } } } }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Human-readable error message" } } }, "content_filter": { "type": "object", "description": "Information about content that was filtered due to safety policies", "properties": { "filtered_count": { "type": "integer", "description": "Number of items filtered" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Human-readable reasons for filtering" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Source video not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/videos/edits": { "post": { "operationId": "videoEdit", "summary": "Edit a video", "description": "Edits an existing video - prompt-driven editing, upscaling, or background removal, selected\nwith `type`. Accepts either `application/json` (with the source as a provider-side ID or a\nURL) or `multipart/form-data` (to upload the source as `video`). Like generation this is an\nasynchronous operation that returns a job ID; poll the retrieve endpoint for completion.\n", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON encoding of a video edit. The source is supplied as a nested `video` object holding either\nan `id` or a `url`. To upload the source as a file, post `multipart/form-data` instead - see\n`VideoEditMultipartRequest`.\n", "required": [ "model", "video" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "video": { "type": "object", "description": "Source video for an edit. Supply exactly one of `id` or `url`. Output geometry and duration are\nderived from the source and are not accepted as parameters.\n", "properties": { "id": { "type": "string", "description": "Provider-side video ID, as returned by a previous generation" }, "url": { "type": "string", "description": "Public URL or data URI" } } }, "prompt": { "type": "string", "description": "Text prompt describing the edit. Required except for operation types driven purely by the\nsource video: `background_removal` and `upscale`.\n" }, "type": { "type": "string", "enum": [ "upscale", "background_removal", "remove_background", "remove_bg" ], "description": "Operation selector. Omit for prompt-driven editing. Support varies by provider; unsupported\nvalues fall back to a standard edit.\n" }, "seed": { "type": "integer", "description": "Seed for reproducible editing" }, "output_format": { "type": "string", "enum": [ "mp4", "webm", "mov" ], "description": "Output container format" }, "upscale_factor": { "type": "integer", "description": "Multiply each dimension by this factor. `type: \"upscale\"` only; mutually exclusive with\n`target_megapixels`.\n" }, "target_megapixels": { "type": "integer", "description": "Target output size in megapixels. `type: \"upscale\"` only; mutually exclusive with\n`upscale_factor`.\n" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } }, "multipart/form-data": { "schema": { "type": "object", "description": "Multipart encoding of a video edit, and the only encoding that can upload a source file. This\nis what the official OpenAI SDKs send unconditionally, flattening the reference form to a\n`video[id]` field. Supply exactly one of `video`, `video[id]` or `video[url]`.\n", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "video": { "type": "string", "format": "binary", "description": "Source video file to upload" }, "video[id]": { "type": "string", "description": "Provider-side video ID, as an alternative to uploading a file" }, "video[url]": { "type": "string", "description": "Public URL of the source video, as an alternative to uploading a file" }, "prompt": { "type": "string", "description": "Text prompt describing the edit. Required except for operation types driven purely by the\nsource video: `background_removal` and `upscale`.\n" }, "type": { "type": "string", "enum": [ "upscale", "background_removal", "remove_background", "remove_bg" ], "description": "Operation selector. Omit for prompt-driven editing" }, "seed": { "type": "integer", "description": "Seed for reproducible editing" }, "output_format": { "type": "string", "enum": [ "mp4", "webm", "mov" ], "description": "Output container format" }, "upscale_factor": { "type": "integer", "description": "`type: \"upscale\"` only; mutually exclusive with `target_megapixels`" }, "target_megapixels": { "type": "integer", "description": "`type: \"upscale\"` only; mutually exclusive with `upscale_factor`" } } } } } }, "responses": { "200": { "description": "Successful response. Returns a video job object with status information.\nPoll the retrieve endpoint to check completion status.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-native job ID. To use in path parameters (retrieve/delete/download), combine as `{id}:{provider}` (e.g., `task_abc123:runway`)" }, "object": { "type": "string", "enum": [ "video" ], "description": "Object type, always \"video\"" }, "model": { "type": "string", "description": "Model used for video generation" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ], "description": "Current lifecycle status of the video generation job:\n- `queued`: Job is waiting to be processed\n- `in_progress`: Video is currently being generated\n- `completed`: Video generation completed successfully\n- `failed`: Video generation failed\n" }, "progress": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Approximate completion percentage (0-100)" }, "prompt": { "type": "string", "description": "Prompt used to generate the video" }, "remixed_from_video_id": { "type": "string", "description": "Source video ID if this is a remix" }, "seconds": { "type": "string", "description": "Duration of the generated video in seconds as a string (e.g., \"4\")" }, "size": { "type": "string", "description": "Resolution of the generated video (e.g., \"1920x1080\")" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job was created" }, "completed_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the job completed" }, "expires_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when downloadable assets expire" }, "videos": { "type": "array", "description": "Generated video outputs (only present when status is \"completed\")", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url", "base64" ], "description": "Output format of this video" }, "url": { "type": "string", "format": "uri", "description": "URL to the generated video (present when type is \"url\")" }, "base64": { "type": "string", "description": "Base64-encoded video content (present when type is \"base64\")" }, "content_type": { "type": "string", "description": "MIME type of the video (e.g., \"video/mp4\")" } } } }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Human-readable error message" } } }, "content_filter": { "type": "object", "description": "Information about content that was filtered due to safety policies", "properties": { "filtered_count": { "type": "integer", "description": "Number of items filtered" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Human-readable reasons for filtering" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/responses/input_tokens": { "post": { "operationId": "countTokens", "summary": "Count tokens", "description": "Counts the number of tokens in the provided messages.\n", "tags": [ "Count Tokens" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountTokensRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/responses/compact": { "post": { "operationId": "createCompaction", "summary": "Compact context", "description": "Compresses a conversation into an opaque encrypted compaction item using the\nOpenAI-compatible context compaction API.\n\nThe response `output` array contains the original user messages plus a final item\nwith `type: \"response.compaction\"` and an `encrypted_content` field. Pass the\nfull `output` array as `input` to future Responses API requests to continue the\nconversation without retransmitting the full history.\n\n**Supported providers:** OpenAI, Azure OpenAI, xAI. Requests to unsupported\nproviders return a 400 error.\n", "tags": [ "Compaction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format (e.g., \"openai/gpt-4o\")" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } } ], "description": "Conversation to compact. Required unless previous_response_id is provided. Can be a string or array of ResponsesMessage objects. Compaction items from prior responses (type \"response.compaction\") may be included in the array.\n" }, "instructions": { "type": "string", "description": "System instructions that persist across the compacted context." }, "previous_response_id": { "type": "string", "description": "ID of a previous response to extend rather than sending full input." }, "prompt_cache_key": { "type": "string" }, "prompt_cache_retention": { "type": "string" }, "service_tier": { "type": "string" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback model list in provider/model format." } } } } } }, "responses": { "200": { "description": "Successful compaction response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "description": "Always \"response.compaction\"", "example": "response.compaction" }, "model": { "type": "string" }, "created_at": { "type": "integer" }, "output": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "description": "The compacted output — the original user messages plus a final item of type \"response.compaction\" whose encrypted_content holds the opaque compacted state. Pass the full output array as input to a future Responses API request.\n" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "input_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "image_tokens": { "type": "integer" }, "cached_read_tokens": { "type": "integer", "description": "Tokens served from the prompt cache (cache hit), billed at the reduced cache-read rate. Already included in the parent input_tokens total.\n" }, "cached_write_tokens": { "type": "integer", "description": "Tokens written to the prompt cache on this request, billed at the cache-creation rate. Already included in the parent input_tokens total. Populated for providers that separately report cache write tokens (Anthropic, Bedrock).\n" } } }, "output_tokens": { "type": "integer" }, "output_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "accepted_prediction_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "rejected_prediction_tokens": { "type": "integer" }, "citation_tokens": { "type": "integer" }, "num_search_queries": { "type": "integer" } } }, "total_tokens": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/BifrostCost" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/responses/{response_id}": { "get": { "operationId": "retrieveResponse", "summary": "Retrieve a response", "description": "Retrieves a stored response by ID.\n", "tags": [ "Responses" ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "description": "The ID of the response to retrieve", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "Provider the response was created with (defaults to `openai`)", "schema": { "$ref": "#/components/schemas/ModelProvider" } }, { "name": "include", "in": "query", "description": "Additional fields to include (repeatable)", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "starting_after", "in": "query", "description": "Sequence number of the event after which to start the response", "schema": { "type": "integer" } }, { "name": "include_obfuscation", "in": "query", "description": "Whether to include obfuscation on the response", "schema": { "type": "boolean" } }, { "name": "stream", "in": "query", "description": "When `true`, replays the stored response as SSE events instead of a single JSON object", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming responses API response (SSE format)", "properties": { "type": { "type": "string", "enum": [ "response.ping", "response.created", "response.in_progress", "response.completed", "response.failed", "response.incomplete", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.refusal.delta", "response.refusal.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.results.added", "response.file_search_call.results.completed", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.web_search_call.results.added", "response.web_search_call.results.completed", "response.web_fetch_call.in_progress", "response.web_fetch_call.fetching", "response.web_fetch_call.completed", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.image_generation_call.completed", "response.image_generation_call.generating", "response.image_generation_call.in_progress", "response.image_generation_call.partial_image", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.mcp_call.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_list_tools.in_progress", "response.code_interpreter_call.in_progress", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.output_text.annotation.added", "response.output_text.annotation.done", "response.queued", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "error" ] }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "output_index": { "type": "integer" }, "item": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "content_index": { "type": "integer" }, "item_id": { "type": "string" }, "part": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "delta": { "type": "string" }, "signature": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "text": { "type": "string" }, "refusal": { "type": "string" }, "arguments": { "type": "string" }, "partial_image_b64": { "type": "string" }, "partial_image_index": { "type": "integer" }, "annotation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } }, "annotation_index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "deleteResponse", "summary": "Delete a response", "description": "Deletes a stored response.\n", "tags": [ "Responses" ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "description": "The ID of the response to delete", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "Provider the response was created with (defaults to `openai`)", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostResponsesDeleteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/responses/{response_id}/cancel": { "post": { "operationId": "cancelResponse", "summary": "Cancel a response", "description": "Cancels an in-flight response. Only responses created with `background: true`\ncan be cancelled.\n", "tags": [ "Responses" ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "description": "The ID of the response to cancel", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "Provider the response was created with (defaults to `openai`)", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/responses/{response_id}/input_items": { "get": { "operationId": "listResponseInputItems", "summary": "List response input items", "description": "Lists the input items of a stored response.\n", "tags": [ "Responses" ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "description": "The ID of the response", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "Provider the response was created with (defaults to `openai`)", "schema": { "$ref": "#/components/schemas/ModelProvider" } }, { "name": "after", "in": "query", "description": "Cursor for pagination (item ID to list items after)", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Additional fields to include (repeatable)", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "Maximum number of input items to return", "schema": { "type": "integer", "minimum": 1 } }, { "name": "order", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostResponsesInputItemsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/batches": { "post": { "operationId": "createBatch", "summary": "Create a batch job", "description": "Creates a batch job for asynchronous processing.\n", "tags": [ "Batch" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "listBatches", "summary": "List batch jobs", "description": "Lists batch jobs for a provider.\n", "tags": [ "Batch" ], "parameters": [ { "name": "provider", "in": "query", "required": true, "description": "Provider to list batches for", "schema": { "$ref": "#/components/schemas/ModelProvider" } }, { "name": "limit", "in": "query", "description": "Maximum number of batches to return", "schema": { "type": "integer", "minimum": 1 } }, { "name": "after", "in": "query", "description": "Cursor for pagination", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Cursor for pagination", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/batches/{batch_id}": { "get": { "operationId": "retrieveBatch", "summary": "Retrieve a batch job", "description": "Retrieves a specific batch job by ID.\n", "tags": [ "Batch" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "description": "The ID of the batch to retrieve", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the batch", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRetrieveResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/batches/{batch_id}/cancel": { "post": { "operationId": "cancelBatch", "summary": "Cancel a batch job", "description": "Cancels a batch job.\n", "tags": [ "Batch" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "description": "The ID of the batch to cancel", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the batch", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string", "enum": [ "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "canceled", "ended" ] }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "succeeded": { "type": "integer" }, "expired": { "type": "integer" }, "canceled": { "type": "integer" }, "pending": { "type": "integer" } } }, "cancelling_at": { "type": "integer", "format": "int64" }, "cancelled_at": { "type": "integer", "format": "int64" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/batches/{batch_id}/results": { "get": { "operationId": "getBatchResults", "summary": "Get batch results", "description": "Retrieves results from a completed batch job.\n", "tags": [ "Batch" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "description": "The ID of the batch", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the batch", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "custom_id": { "type": "string" }, "response": { "type": "object", "properties": { "status_code": { "type": "integer" }, "request_id": { "type": "string" }, "body": { "type": "object" } } }, "result": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/files": { "post": { "operationId": "uploadFile", "summary": "Upload a file", "description": "Uploads a file to be used with batch operations or other features.\n", "tags": [ "Files" ], "parameters": [ { "name": "provider", "in": "query", "description": "Provider to upload file to (can also use x-model-provider header)", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FileUploadRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "listFiles", "summary": "List files", "description": "Lists files for a provider.\n", "tags": [ "Files" ], "parameters": [ { "name": "x-model-provider", "in": "query", "required": true, "description": "Provider to list files for", "schema": { "$ref": "#/components/schemas/ModelProvider" } }, { "name": "purpose", "in": "query", "description": "Filter by purpose", "schema": { "type": "string", "enum": [ "batch", "assistants", "fine-tune", "vision", "batch_output", "user_data", "responses", "evals" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return", "schema": { "type": "integer", "minimum": 1 } }, { "name": "after", "in": "query", "description": "Cursor for pagination", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order (asc/desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/files/{file_id}": { "get": { "operationId": "retrieveFile", "summary": "Retrieve file metadata", "description": "Retrieves metadata for a specific file.\n", "tags": [ "Files" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the file", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "integer", "format": "int64" }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "batch", "assistants", "fine-tune", "vision", "batch_output", "user_data", "responses", "evals" ] }, "status": { "type": "string", "enum": [ "uploaded", "processed", "processing", "error", "deleted" ] }, "status_details": { "type": "string" }, "expires_at": { "type": "integer", "format": "int64" }, "storage_backend": { "type": "string" }, "storage_uri": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "deleteFile", "summary": "Delete a file", "description": "Deletes a file.\n", "tags": [ "Files" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to delete", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the file", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/files/{file_id}/content": { "get": { "operationId": "getFileContent", "summary": "Download file content", "description": "Downloads the content of a file.\n", "tags": [ "Files" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the file", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/containers": { "post": { "operationId": "createContainer", "summary": "Create a container", "description": "Creates a new container for storing files and data.\n", "tags": [ "Containers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "name" ], "properties": { "provider": { "$ref": "#/components/schemas/ModelProvider" }, "name": { "type": "string", "description": "Name of the container" }, "expires_after": { "type": "object", "description": "Expiration configuration for a container", "properties": { "anchor": { "type": "string", "description": "The anchor point for expiration (e.g., \"last_active_at\")" }, "minutes": { "type": "integer", "description": "Number of minutes after anchor point" } } }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of existing files to copy into this container" }, "memory_limit": { "type": "string", "description": "Memory limit for the container (e.g., \"1g\", \"4g\")" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User-provided metadata" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the created container" }, "object": { "type": "string", "description": "The object type (always \"container\")" }, "name": { "type": "string", "description": "The name of the container" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the container was created" }, "status": { "type": "string", "enum": [ "running" ], "description": "The status of a container" }, "expires_after": { "type": "object", "description": "Expiration configuration for a container", "properties": { "anchor": { "type": "string", "description": "The anchor point for expiration (e.g., \"last_active_at\")" }, "minutes": { "type": "integer", "description": "Number of minutes after anchor point" } } }, "last_active_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of last activity" }, "memory_limit": { "type": "string", "description": "Memory limit for the container" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User-provided metadata" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "listContainers", "summary": "List containers", "description": "Lists containers for a provider.\n", "tags": [ "Containers" ], "parameters": [ { "name": "provider", "in": "query", "required": true, "description": "Provider to list containers for", "schema": { "$ref": "#/components/schemas/ModelProvider" } }, { "name": "limit", "in": "query", "description": "Maximum number of containers to return (1-100, default 20)", "schema": { "type": "integer", "minimum": 1, "limit": 200, "maximum": 100 } }, { "name": "after", "in": "query", "description": "Cursor for pagination", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order (asc/desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type (always \"list\")" }, "data": { "type": "array", "items": { "type": "object", "description": "A container object", "properties": { "id": { "type": "string", "description": "The unique identifier for the container" }, "object": { "type": "string", "description": "The object type (always \"container\")" }, "name": { "type": "string", "description": "The name of the container" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the container was created" }, "status": { "type": "string", "enum": [ "running" ], "description": "The status of a container" }, "expires_after": { "type": "object", "description": "Expiration configuration for a container", "properties": { "anchor": { "type": "string", "description": "The anchor point for expiration (e.g., \"last_active_at\")" }, "minutes": { "type": "integer", "description": "Number of minutes after anchor point" } } }, "last_active_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of last activity" }, "memory_limit": { "type": "string", "description": "Memory limit for the container (e.g., \"1g\", \"4g\")" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User-provided metadata" } } }, "description": "List of container objects" }, "first_id": { "type": "string", "description": "ID of the first container in the list" }, "last_id": { "type": "string", "description": "ID of the last container in the list" }, "has_more": { "type": "boolean", "description": "Whether there are more containers to fetch" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/containers/{container_id}": { "get": { "operationId": "retrieveContainer", "summary": "Retrieve a container", "description": "Retrieves a specific container by ID.\n", "tags": [ "Containers" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "description": "The ID of the container to retrieve", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the container", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the container" }, "object": { "type": "string", "description": "The object type (always \"container\")" }, "name": { "type": "string", "description": "The name of the container" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the container was created" }, "status": { "type": "string", "enum": [ "running" ], "description": "The status of a container" }, "expires_after": { "type": "object", "description": "Expiration configuration for a container", "properties": { "anchor": { "type": "string", "description": "The anchor point for expiration (e.g., \"last_active_at\")" }, "minutes": { "type": "integer", "description": "Number of minutes after anchor point" } } }, "last_active_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of last activity" }, "memory_limit": { "type": "string", "description": "Memory limit for the container" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User-provided metadata" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "deleteContainer", "summary": "Delete a container", "description": "Deletes a container.\n", "tags": [ "Containers" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "description": "The ID of the container to delete", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the container", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the deleted container" }, "object": { "type": "string", "description": "The object type (always \"container.deleted\")" }, "deleted": { "type": "boolean", "description": "Whether the container was successfully deleted" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/containers/{container_id}/files": { "post": { "operationId": "createContainerFile", "summary": "Create a file in a container", "description": "Creates a new file in a container. You can either upload file content directly\nvia multipart/form-data or reference an existing file by its ID.\n", "tags": [ "Containers" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "description": "The ID of the container", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the container", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Request to create a file in a container via multipart upload", "properties": { "file": { "type": "string", "format": "binary", "description": "The file content to upload" }, "file_path": { "type": "string", "description": "Optional path for the file within the container" } } } }, "application/json": { "schema": { "type": "object", "description": "Request to create a file in a container by referencing an existing file", "required": [ "file_id" ], "properties": { "file_id": { "type": "string", "description": "The ID of an existing file to copy into the container" }, "file_path": { "type": "string", "description": "Optional path for the file within the container" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Response from creating a file in a container", "properties": { "id": { "type": "string", "description": "The unique identifier for the created file" }, "object": { "type": "string", "description": "The object type (always \"container.file\")" }, "container_id": { "type": "string", "description": "The ID of the container this file belongs to" }, "path": { "type": "string", "description": "The path of the file within the container" }, "bytes": { "type": "integer", "format": "int64", "description": "The size of the file in bytes" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the file was created" }, "source": { "type": "string", "description": "The source of the file" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "listContainerFiles", "summary": "List files in a container", "description": "Lists all files in a container.\n", "tags": [ "Containers" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "description": "The ID of the container", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the container", "schema": { "$ref": "#/components/schemas/ModelProvider" } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "in": "query", "description": "Cursor for pagination", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order (asc/desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Response containing a list of files in a container", "properties": { "object": { "type": "string", "description": "The object type (always \"list\")" }, "data": { "type": "array", "items": { "type": "object", "description": "A file object within a container", "properties": { "id": { "type": "string", "description": "The unique identifier for the file" }, "object": { "type": "string", "description": "The object type (always \"container.file\")" }, "container_id": { "type": "string", "description": "The ID of the container this file belongs to" }, "path": { "type": "string", "description": "The path of the file within the container" }, "bytes": { "type": "integer", "format": "int64", "description": "The size of the file in bytes" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the file was created" }, "source": { "type": "string", "description": "The source of the file (e.g., \"user_upload\", \"copied\")" } } }, "description": "List of file objects" }, "first_id": { "type": "string", "description": "ID of the first file in the list" }, "last_id": { "type": "string", "description": "ID of the last file in the list" }, "has_more": { "type": "boolean", "description": "Whether there are more files to fetch" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/containers/{container_id}/files/{file_id}": { "get": { "operationId": "retrieveContainerFile", "summary": "Retrieve a file from a container", "description": "Retrieves metadata for a specific file in a container.\n", "tags": [ "Containers" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "description": "The ID of the container", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the container", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Response from retrieving a file from a container", "properties": { "id": { "type": "string", "description": "The unique identifier for the file" }, "object": { "type": "string", "description": "The object type (always \"container.file\")" }, "container_id": { "type": "string", "description": "The ID of the container this file belongs to" }, "path": { "type": "string", "description": "The path of the file within the container" }, "bytes": { "type": "integer", "format": "int64", "description": "The size of the file in bytes" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the file was created" }, "source": { "type": "string", "description": "The source of the file" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "deleteContainerFile", "summary": "Delete a file from a container", "description": "Deletes a file from a container.\n", "tags": [ "Containers" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "description": "The ID of the container", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to delete", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the container", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Response from deleting a file from a container", "properties": { "id": { "type": "string", "description": "The ID of the deleted file" }, "object": { "type": "string", "description": "The object type (always \"container.file.deleted\")" }, "deleted": { "type": "boolean", "description": "Whether the file was successfully deleted" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/containers/{container_id}/files/{file_id}/content": { "get": { "operationId": "getContainerFileContent", "summary": "Download file content from a container", "description": "Downloads the content of a file from a container.\n", "tags": [ "Containers" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "description": "The ID of the container", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": true, "description": "The provider of the container", "schema": { "$ref": "#/components/schemas/ModelProvider" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/chat/completions": { "post": { "operationId": "createAsyncChatCompletion", "summary": "Create async chat completion", "description": "Submits a chat completion request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\nStreaming is not supported for async requests.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/completions": { "post": { "operationId": "createAsyncTextCompletion", "summary": "Create async text completion", "description": "Submits a text completion request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\nStreaming is not supported for async requests.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextCompletionRequest" } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/responses": { "post": { "operationId": "createAsyncResponse", "summary": "Create async response", "description": "Submits a response request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\nStreaming is not supported for async requests.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/embeddings": { "post": { "operationId": "createAsyncEmbedding", "summary": "Create async embedding", "description": "Submits an embedding request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/audio/speech": { "post": { "operationId": "createAsyncSpeech", "summary": "Create async speech", "description": "Submits a speech synthesis request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\nSSE streaming is not supported for async requests.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechRequest" } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/audio/transcriptions": { "post": { "operationId": "createAsyncTranscription", "summary": "Create async transcription", "description": "Submits a transcription request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\nStreaming is not supported for async requests.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TranscriptionRequest" } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/images/generations": { "post": { "operationId": "createAsyncImageGeneration", "summary": "Create async image generation", "description": "Submits an image generation request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\nStreaming is not supported for async requests.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "prompt": { "type": "string", "description": "Text prompt to generate image" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of images to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the generated image" }, "quality": { "type": "string", "enum": [ "auto", "high", "medium", "low", "hd", "standard" ], "description": "Quality of the generated image" }, "style": { "type": "string", "enum": [ "natural", "vivid" ], "description": "Style of the generated image" }, "response_format": { "type": "string", "enum": [ "url", "b64_json", "data_uri" ], "default": "url", "description": "Format of the response. `data_uri` is supported by providers that return an inline\ndata URI (e.g. Runware).\n" }, "input_images": { "type": "array", "items": { "type": "string" }, "description": "Input images for image-to-image generation, as public URLs, provider-side asset IDs,\nor base64 data URIs. Providers that accept only a single input use the first entry.\n" }, "aspect_ratio": { "type": "string", "description": "Aspect ratio of the generated image (e.g. `16:9`), for providers that accept one in place of `size`" }, "type": { "type": "string", "description": "Operation selector for providers that expose more than one generation task\n(e.g. `vectorize` for text-to-SVG on Runware). Omit for standard generation.\n" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Background type for the image" }, "moderation": { "type": "string", "enum": [ "low", "auto" ], "description": "Content moderation level" }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Number of partial images to generate" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression level (0-100%)" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg", "tiff", "svg" ], "description": "Output image format. `svg` applies to vectorize operations" }, "user": { "type": "string", "description": "User identifier for tracking" }, "seed": { "type": "integer", "description": "Seed for reproducible image generation" }, "negative_prompt": { "type": "string", "description": "Negative prompt to guide what to avoid in generation" }, "num_inference_steps": { "type": "integer", "description": "Number of inference steps for generation" }, "stream": { "type": "boolean", "default": false, "description": "Whether to stream the response. When true, images are sent as SSE.\nWhen streaming, providers may return base64 chunks (`b64_json`) and/or URLs (`url`) depending on provider and configuration.\n" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } ] } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/images/edits": { "post": { "operationId": "createAsyncImageEdit", "summary": "Create async image edit", "description": "Submits an image edit request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\nStreaming is not supported for async requests.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON encoding of an image edit. Sources are supplied as an `images` array, the same nested form\n/v1/videos/edits uses for its source video. Unrecognised top-level fields are forwarded to the\nprovider as extra params with their JSON types intact, which is what a model's nested tuning\nobject needs (e.g. Runware's `settings` and `providerSettings`). To upload the image as a file,\npost `multipart/form-data` instead - see `ImageEditMultipartRequest`.\n", "required": [ "model", "images" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "images": { "type": "array", "items": { "description": "One source image, either as a bare string - the form `input_images` takes on\n/v1/images/generations - or as an object naming which arm it fills. Providers that cannot accept\na given form reject it.\n", "oneOf": [ { "type": "string", "description": "Public URL, data URI, base64 payload, or provider-side asset ID. Equivalent to the object\nform's `url`.\n" }, { "type": "object", "description": "Exactly one of the two properties is expected.", "properties": { "url": { "type": "string", "description": "Public URL, data URI, or provider-side asset ID, for providers whose upstream fetches\nthe asset itself (e.g. Runware). Avoids round-tripping the asset through the gateway as\nbase64.\n" }, "image": { "type": "string", "format": "byte", "description": "Base64-encoded image bytes" } } } ] }, "description": "Source images. Entries carrying neither a URL nor bytes are dropped; a request left with no\nusable image is rejected. Providers treat the first image as the primary one (Runware's seed\nimage, Bedrock's style-transfer base), so the order is part of the contract. Only the\nreference-image models accept more than one; elsewhere images after the first are dropped.\n" }, "prompt": { "type": "string", "description": "Text prompt describing the edit. Required except for the operation types that are driven\npurely by the input image: `background_removal`, `erase_object`, `upscale`, `upscale_fast`,\n`mask`, `segmentation`, `vectorize` and `controlnet_preprocess`.\n" }, "mask": { "type": "string", "format": "byte", "description": "Optional base64-encoded mask image for inpainting (transparent areas indicate regions to\nedit). Dropped for models that declare no mask input.\n" }, "type": { "type": "string", "enum": [ "inpainting", "outpainting", "background_removal", "remove_background", "remove_bg", "erase_object", "recolor", "search_replace", "control_sketch", "control_structure", "style_guide", "style_transfer", "upscale", "upscale_fast", "upscale_creative", "upscale_conservative", "mask", "segmentation", "vectorize", "controlnet_preprocess", "controlnet", "preprocess" ], "description": "Type of edit operation. Support varies by provider; unsupported values are dropped and the\nrequest runs as a standard edit.\n" }, "upscale_factor": { "type": "integer", "description": "Multiply each dimension by this factor. `type: \"upscale\"` only; mutually exclusive with\n`target_megapixels`.\n" }, "target_megapixels": { "type": "integer", "description": "Target output size in megapixels. `type: \"upscale\"` only; mutually exclusive with\n`upscale_factor`.\n" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of images to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "auto" ], "description": "Size of the output image" }, "response_format": { "type": "string", "enum": [ "url", "b64_json", "data_uri" ], "default": "url", "description": "Format of the response. `data_uri` is supported by providers that return an inline\ndata URI (e.g. Runware).\n" }, "stream": { "type": "boolean", "default": false, "description": "When true, stream the response via Server-Sent Events" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Background type for the image" }, "input_fidelity": { "type": "string", "enum": [ "low", "high" ], "description": "How closely to follow the original image" }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Number of partial images to generate when streaming" }, "quality": { "type": "string", "enum": [ "auto", "high", "medium", "low", "standard" ], "description": "Quality of the output image" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg", "tiff", "svg" ], "description": "Output image format. `svg` applies to vectorize operations" }, "num_inference_steps": { "type": "integer", "description": "Number of inference steps" }, "seed": { "type": "integer", "description": "Seed for reproducible editing" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression level (0-100%)" }, "negative_prompt": { "type": "string", "description": "What to avoid in the edit" }, "user": { "type": "string", "description": "User identifier for tracking" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } }, "multipart/form-data": { "schema": { "type": "object", "description": "Multipart encoding of an image edit, and the only encoding that can upload the image as a file.\nThis is what the official OpenAI SDKs send unconditionally. Every value crosses the wire as a\nstring, so provider-native extra params arrive as strings; post `application/json` instead when\na provider expects them as numbers, booleans or nested objects - see `ImageEditRequest`.\n", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "prompt": { "type": "string", "description": "Text prompt describing the edit. Required except for the operation types that are driven\npurely by the input image: `background_removal`, `erase_object`, `upscale`, `upscale_fast`,\n`mask`, `segmentation`, `vectorize` and `controlnet_preprocess`.\n" }, "image": { "type": "string", "format": "binary", "description": "Image file to edit. Use field name `image` for a single file or `image[]` for multiple files.\nEither `image` or `image_url` is required.\n" }, "image_url": { "type": "string", "description": "Input image as a public URL or provider-side asset ID, for providers whose upstream fetches\nthe asset itself (e.g. Runware). Use `image_url` for one or `image_url[]` for several; this\navoids round-tripping the asset through the gateway as base64. Uploads keep their leading\nposition, and providers treat the first image as the primary one.\n" }, "mask": { "type": "string", "format": "binary", "description": "Optional mask image for inpainting (transparent areas indicate regions to edit). Dropped for\nmodels that declare no mask input.\n" }, "type": { "type": "string", "enum": [ "inpainting", "outpainting", "background_removal", "remove_background", "remove_bg", "erase_object", "recolor", "search_replace", "control_sketch", "control_structure", "style_guide", "style_transfer", "upscale", "upscale_fast", "upscale_creative", "upscale_conservative", "mask", "segmentation", "vectorize", "controlnet_preprocess", "controlnet", "preprocess" ], "description": "Type of edit operation. Support varies by provider; unsupported values are dropped and the\nrequest runs as a standard edit.\n" }, "upscale_factor": { "type": "integer", "description": "Multiply each dimension by this factor. `type: \"upscale\"` only; mutually exclusive with\n`target_megapixels`.\n" }, "target_megapixels": { "type": "integer", "description": "Target output size in megapixels. `type: \"upscale\"` only; mutually exclusive with\n`upscale_factor`.\n" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of images to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "auto" ], "description": "Size of the output image" }, "response_format": { "type": "string", "enum": [ "url", "b64_json", "data_uri" ], "default": "url", "description": "Format of the response. `data_uri` is supported by providers that return an inline\ndata URI (e.g. Runware).\n" }, "stream": { "type": "boolean", "default": false, "description": "When true, stream the response via Server-Sent Events" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Background type for the image" }, "input_fidelity": { "type": "string", "enum": [ "low", "high" ], "description": "How closely to follow the original image" }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Number of partial images to generate when streaming" }, "quality": { "type": "string", "enum": [ "auto", "high", "medium", "low", "standard" ], "description": "Quality of the output image" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg", "tiff", "svg" ], "description": "Output image format. `svg` applies to vectorize operations" }, "num_inference_steps": { "type": "integer", "description": "Number of inference steps" }, "seed": { "type": "integer", "description": "Seed for reproducible editing" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression level (0-100%)" }, "negative_prompt": { "type": "string", "description": "What to avoid in the edit" }, "user": { "type": "string", "description": "User identifier for tracking" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/images/variations": { "post": { "operationId": "createAsyncImageVariation", "summary": "Create async image variation", "description": "Submits an image variation request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "model", "image" ], "properties": { "model": { "type": "string", "description": "Model identifier in format `provider/model`" }, "image": { "type": "string", "format": "binary", "description": "Image file to create variations of. Use field name `image` for a single file or `image[]` for multiple (first image is used).\n" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of variations to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the output images" }, "response_format": { "type": "string", "enum": [ "url", "b64_json" ], "default": "url", "description": "Format of the response" }, "user": { "type": "string", "description": "User identifier for tracking" }, "fallbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Fallback" }, "description": "Fallback models to try if primary model fails" } } } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/chat/completions/{job_id}": { "get": { "operationId": "getAsyncChatCompletionJob", "summary": "Get async chat completion job", "description": "Retrieves the status and result of an async chat completion job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/completions/{job_id}": { "get": { "operationId": "getAsyncTextCompletionJob", "summary": "Get async text completion job", "description": "Retrieves the status and result of an async text completion job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/responses/{job_id}": { "get": { "operationId": "getAsyncResponseJob", "summary": "Get async response job", "description": "Retrieves the status and result of an async response job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/embeddings/{job_id}": { "get": { "operationId": "getAsyncEmbeddingJob", "summary": "Get async embedding job", "description": "Retrieves the status and result of an async embedding job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/audio/speech/{job_id}": { "get": { "operationId": "getAsyncSpeechJob", "summary": "Get async speech job", "description": "Retrieves the status and result of an async speech job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/audio/transcriptions/{job_id}": { "get": { "operationId": "getAsyncTranscriptionJob", "summary": "Get async transcription job", "description": "Retrieves the status and result of an async transcription job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/images/generations/{job_id}": { "get": { "operationId": "getAsyncImageGenerationJob", "summary": "Get async image generation job", "description": "Retrieves the status and result of an async image generation job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/images/edits/{job_id}": { "get": { "operationId": "getAsyncImageEditJob", "summary": "Get async image edit job", "description": "Retrieves the status and result of an async image edit job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/images/variations/{job_id}": { "get": { "operationId": "getAsyncImageVariationJob", "summary": "Get async image variation job", "description": "Retrieves the status and result of an async image variation job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/rerank": { "post": { "operationId": "createAsyncRerank", "summary": "Create async rerank", "description": "Submits a rerank request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" }, { "$ref": "#/components/parameters/AsyncWebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/rerank/{job_id}": { "get": { "operationId": "getAsyncRerankJob", "summary": "Get async rerank job", "description": "Retrieves the status and result of an async rerank job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/ocr": { "post": { "operationId": "createAsyncOCR", "summary": "Create async OCR job", "description": "Submits an OCR request for asynchronous execution. Returns a job ID immediately\nwith HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncResultTTL" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCRRequest" } } } }, "responses": { "202": { "description": "Job accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/async/ocr/{job_id}": { "get": { "operationId": "getAsyncOCRJob", "summary": "Get async OCR job", "description": "Retrieves the status and result of an async OCR job.\nReturns HTTP 202 if the job is still pending or processing, HTTP 200 if completed or failed.\n", "tags": [ "Async Jobs" ], "parameters": [ { "$ref": "#/components/parameters/AsyncJobId" } ], "responses": { "200": { "description": "Job completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "202": { "description": "Job is still pending or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/realtime": { "get": { "operationId": "connectRealtime", "summary": "Realtime API WebSocket", "description": "Opens a bidirectional WebSocket session to a realtime-capable provider\n(e.g. OpenAI Realtime, Azure Realtime preview). Bifrost proxies the upstream\nsocket and applies governance, observability, and key selection on connect.\n\nThe target model is provided via the `model` query parameter (or `deployment`\nfor Azure-style routes). The OpenAI SDK sends the API key over the\n`openai-insecure-api-key.` WebSocket subprotocol; Bifrost extracts it and\ntreats it the same as a Bearer header.\n\nInference auth applies — Bearer/Basic/Virtual Key/API Key headers are all\naccepted, plus the subprotocol form above.\n", "tags": [ "Realtime" ], "parameters": [ { "name": "model", "in": "query", "required": false, "description": "Provider model identifier in `provider/model` form (e.g. `openai/gpt-4o-realtime-preview`).\nEither `model` or `deployment` must be supplied; requests with neither (or both) are rejected with HTTP 400 before the WebSocket upgrade completes.\n", "schema": { "type": "string" } }, { "name": "deployment", "in": "query", "required": false, "description": "Azure deployment name (for Azure-style routes).", "schema": { "type": "string" } }, { "name": "Upgrade", "in": "header", "required": true, "description": "Must be `websocket`", "schema": { "type": "string", "enum": [ "websocket" ] } }, { "name": "Sec-WebSocket-Protocol", "in": "header", "required": false, "description": "Optional WebSocket subprotocol. Use `openai-insecure-api-key.` to\nauthenticate when headers cannot be supplied by the client.\n", "schema": { "type": "string" } } ], "responses": { "101": { "description": "Switching Protocols — WebSocket upgrade succeeded" }, "400": { "description": "Invalid model/provider or unsupported realtime configuration" }, "401": { "description": "Authentication failed" } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/realtime/calls": { "post": { "operationId": "createRealtimeCall", "summary": "Realtime WebRTC SDP exchange", "description": "Negotiates a WebRTC peer connection with the realtime provider on behalf of\nthe client. Implements the OpenAI GA `/realtime/calls` contract: the request\nbody is `multipart/form-data` with `sdp` (client SDP offer) and `session`\n(JSON session description containing `model`).\n\nBifrost forwards the offer to the upstream provider, returns the upstream\nSDP answer to the client, and pipes RTP media between the two peers for the\nlifetime of the session.\n\nInference auth applies (Bearer/Basic/Virtual Key/API Key).\n", "tags": [ "Realtime" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "sdp", "session" ], "properties": { "sdp": { "type": "string", "description": "Client-generated SDP offer" }, "session": { "type": "string", "description": "JSON-encoded session descriptor. `session.model` is required and\nmust be in `provider/model` form.\n" } } } }, "application/sdp": { "schema": { "type": "string", "description": "Legacy raw-SDP format (beta). When using this content type, supply\nthe model via the `?model=` query parameter instead of the session\nJSON. Used by older OpenAI SDKs.\n" } } } }, "responses": { "200": { "description": "SDP answer from the upstream realtime provider", "content": { "application/sdp": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "401": { "description": "Authentication failed" }, "502": { "description": "Upstream provider rejected the SDP exchange" } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/realtime/client_secrets": { "post": { "operationId": "createRealtimeClientSecret", "summary": "Mint a realtime ephemeral client secret", "description": "Calls the upstream realtime provider's `client_secrets` endpoint to mint a\nshort-lived ephemeral token (e.g. for browser-based WebRTC clients).\nBifrost selects a provider key, evaluates governance, and proxies the\nresponse. The returned token is cached and mapped to the originating\nvirtual key for downstream attribution.\n\nRequest body must be JSON. `session.model` (or top-level `model`) must use\n`provider/model` form.\n", "tags": [ "Realtime" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provider-specific realtime client-secret payload (passthrough)." } } } }, "responses": { "200": { "description": "Upstream client-secret response (provider passthrough)", "content": { "application/json": { "schema": { "type": "object", "description": "Provider-specific response body" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "401": { "description": "Authentication failed" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/realtime/sessions": { "post": { "operationId": "createRealtimeSession", "summary": "Mint a realtime session (legacy alias)", "description": "Legacy alias for the realtime client-secret minting endpoint. Behaves\nidentically to `createRealtimeClientSecret` but uses the `sessions` route\nshape; provided for compatibility with older OpenAI Realtime client\nlibraries.\n", "tags": [ "Realtime" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provider-specific realtime session payload (passthrough)." } } } }, "responses": { "200": { "description": "Upstream session response (provider passthrough)", "content": { "application/json": { "schema": { "type": "object", "description": "Provider-specific response body" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "401": { "description": "Authentication failed" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/chat/completions": { "post": { "operationId": "openaiCreateChatCompletion", "summary": "Create chat completion (OpenAI format)", "description": "Creates a chat completion using OpenAI-compatible format.\nSupports streaming via SSE.\n\n**Async inference:** Send `x-bf-async: true` to submit the request as a background job and receive a job ID immediately. Poll with `x-bf-async-id: ` to retrieve the result. When the job is still processing, the response will have an empty `choices` array. When completed, `choices` will contain the full result. See [Async Inference](/features/async-inference) for details.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/chat/completions`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "x-bf-async", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Set to `true` to submit this request as an async job. Returns immediately with a job ID. Not compatible with streaming." }, { "name": "x-bf-async-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Poll for results of a previously submitted async job by providing the job ID returned from the initial async request." }, { "name": "x-bf-async-job-result-ttl", "in": "header", "required": false, "schema": { "type": "integer", "default": 3600 }, "description": "Override the default result TTL in seconds. Results expire after this duration from completion time." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming chat completion response (SSE format)", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "created": { "type": "integer" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/openai/deployments/{deployment-id}/chat/completions": { "post": { "operationId": "azureCreateChatCompletion", "summary": "Create chat completion (Azure OpenAI)", "description": "Creates a chat completion using Azure OpenAI deployment.\n", "tags": [ "OpenAI Integration", "Azure Integration" ], "parameters": [ { "name": "deployment-id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Azure deployment ID" }, { "name": "api-version", "in": "query", "schema": { "type": "string" }, "description": "Azure API version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming chat completion response (SSE format)", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "created": { "type": "integer" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/completions": { "post": { "operationId": "openaiCreateTextCompletion", "summary": "Create text completion (OpenAI format)", "description": "Creates a text completion using OpenAI-compatible format.\nThis is the legacy completions API.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/completions`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAITextCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming text completion response", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/openai/deployments/{deployment-id}/completions": { "post": { "operationId": "azureCreateTextCompletion", "summary": "Create text completion (Azure OpenAI)", "tags": [ "OpenAI Integration", "Azure Integration" ], "parameters": [ { "name": "deployment-id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Azure deployment ID" }, { "name": "api-version", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAITextCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming text completion response", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/responses": { "post": { "operationId": "openaiCreateResponse", "summary": "Create response (OpenAI Responses API)", "description": "Creates a response using OpenAI Responses API format.\nSupports streaming via SSE.\n\n**Async inference:** Send `x-bf-async: true` to submit the request as a background job and receive a job ID immediately. Poll with `x-bf-async-id: ` to retrieve the result. When the job is still processing, the response `status` will not be `completed`. When completed, the full response with `output_text` will be returned. See [Async Inference](/features/async-inference) for details.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/responses`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "x-bf-async", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Set to `true` to submit this request as an async job. Returns immediately with a job ID. Not compatible with streaming." }, { "name": "x-bf-async-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Poll for results of a previously submitted async job by providing the job ID returned from the initial async request." }, { "name": "x-bf-async-job-result-ttl", "in": "header", "required": false, "schema": { "type": "integer", "default": 3600 }, "description": "Override the default result TTL in seconds. Results expire after this duration from completion time." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming responses API response (SSE format)", "properties": { "type": { "type": "string", "enum": [ "response.ping", "response.created", "response.in_progress", "response.completed", "response.failed", "response.incomplete", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.refusal.delta", "response.refusal.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.results.added", "response.file_search_call.results.completed", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.web_search_call.results.added", "response.web_search_call.results.completed", "response.web_fetch_call.in_progress", "response.web_fetch_call.fetching", "response.web_fetch_call.completed", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.image_generation_call.completed", "response.image_generation_call.generating", "response.image_generation_call.in_progress", "response.image_generation_call.partial_image", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.mcp_call.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_list_tools.in_progress", "response.code_interpreter_call.in_progress", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.output_text.annotation.added", "response.output_text.annotation.done", "response.queued", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "error" ] }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "output_index": { "type": "integer" }, "item": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "content_index": { "type": "integer" }, "item_id": { "type": "string" }, "part": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "delta": { "type": "string" }, "signature": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "text": { "type": "string" }, "refusal": { "type": "string" }, "arguments": { "type": "string" }, "partial_image_b64": { "type": "string" }, "partial_image_index": { "type": "integer" }, "annotation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } }, "annotation_index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "openaiResponsesWebSocket", "summary": "WebSocket Responses (OpenAI alias)", "description": "WebSocket upgrade endpoint for the Responses API. Mirrors the canonical\n`GET /v1/responses` WS endpoint; the OpenAI-prefixed path is selected\nwhen the request includes an `Upgrade: websocket` header.\nAuthentication accepts the same headers as the inference HTTP surface\nplus the `openai-insecure-api-key.` subprotocol fallback.\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "Upgrade", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "websocket" ] } }, { "name": "Sec-WebSocket-Protocol", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional subprotocol; supports `openai-insecure-api-key.` for\nSDK-style auth.\n" } ], "responses": { "101": { "description": "WebSocket connection established." }, "401": { "description": "Unauthorized." }, "429": { "description": "Maximum concurrent WebSocket connections reached." } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/openai/deployments/{deployment-id}/responses": { "post": { "operationId": "azureCreateResponse", "summary": "Create response (Azure OpenAI)", "tags": [ "OpenAI Integration", "Azure Integration" ], "parameters": [ { "name": "deployment-id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Azure deployment ID" }, { "name": "api-version", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming responses API response (SSE format)", "properties": { "type": { "type": "string", "enum": [ "response.ping", "response.created", "response.in_progress", "response.completed", "response.failed", "response.incomplete", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.refusal.delta", "response.refusal.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.results.added", "response.file_search_call.results.completed", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.web_search_call.results.added", "response.web_search_call.results.completed", "response.web_fetch_call.in_progress", "response.web_fetch_call.fetching", "response.web_fetch_call.completed", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.image_generation_call.completed", "response.image_generation_call.generating", "response.image_generation_call.in_progress", "response.image_generation_call.partial_image", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.mcp_call.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_list_tools.in_progress", "response.code_interpreter_call.in_progress", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.output_text.annotation.added", "response.output_text.annotation.done", "response.queued", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "error" ] }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "output_index": { "type": "integer" }, "item": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "content_index": { "type": "integer" }, "item_id": { "type": "string" }, "part": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "delta": { "type": "string" }, "signature": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "text": { "type": "string" }, "refusal": { "type": "string" }, "arguments": { "type": "string" }, "partial_image_b64": { "type": "string" }, "partial_image_index": { "type": "integer" }, "annotation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } }, "annotation_index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/responses/input_tokens": { "post": { "operationId": "openaiCountInputTokens", "summary": "Count input tokens", "description": "Counts the number of tokens in a Responses API request.\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/responses/{response_id}": { "get": { "operationId": "openaiRetrieveResponse", "summary": "Retrieve a response (OpenAI format)", "description": "Retrieves a stored response by ID.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/responses/{response_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the response to retrieve" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider the response was created with (defaults to `openai`)" }, { "name": "include", "in": "query", "description": "Additional fields to include (repeatable)", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "starting_after", "in": "query", "description": "Sequence number of the event after which to start the response", "schema": { "type": "integer" } }, { "name": "include_obfuscation", "in": "query", "description": "Whether to include obfuscation on the response", "schema": { "type": "boolean" } }, { "name": "stream", "in": "query", "description": "When `true`, replays the stored response as SSE events instead of a single JSON object", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming responses API response (SSE format)", "properties": { "type": { "type": "string", "enum": [ "response.ping", "response.created", "response.in_progress", "response.completed", "response.failed", "response.incomplete", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.refusal.delta", "response.refusal.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.results.added", "response.file_search_call.results.completed", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.web_search_call.results.added", "response.web_search_call.results.completed", "response.web_fetch_call.in_progress", "response.web_fetch_call.fetching", "response.web_fetch_call.completed", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.image_generation_call.completed", "response.image_generation_call.generating", "response.image_generation_call.in_progress", "response.image_generation_call.partial_image", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.mcp_call.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_list_tools.in_progress", "response.code_interpreter_call.in_progress", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.output_text.annotation.added", "response.output_text.annotation.done", "response.queued", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "error" ] }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "output_index": { "type": "integer" }, "item": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "content_index": { "type": "integer" }, "item_id": { "type": "string" }, "part": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "delta": { "type": "string" }, "signature": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "text": { "type": "string" }, "refusal": { "type": "string" }, "arguments": { "type": "string" }, "partial_image_b64": { "type": "string" }, "partial_image_index": { "type": "integer" }, "annotation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } }, "annotation_index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "openaiDeleteResponse", "summary": "Delete a response (OpenAI format)", "description": "Deletes a stored response.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/responses/{response_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the response to delete" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider the response was created with (defaults to `openai`)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostResponsesDeleteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/responses/{response_id}/cancel": { "post": { "operationId": "openaiCancelResponse", "summary": "Cancel a response (OpenAI format)", "description": "Cancels an in-flight response. Only responses created with `background: true`\ncan be cancelled.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/responses/{response_id}/cancel`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the response to cancel" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider the response was created with (defaults to `openai`)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/responses/{response_id}/input_items": { "get": { "operationId": "openaiListResponseInputItems", "summary": "List response input items (OpenAI format)", "description": "Lists the input items of a stored response.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/responses/{response_id}/input_items`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the response" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider the response was created with (defaults to `openai`)" }, { "name": "after", "in": "query", "description": "Cursor for pagination (item ID to list items after)", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Additional fields to include (repeatable)", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "Maximum number of input items to return", "schema": { "type": "integer", "minimum": 1 } }, { "name": "order", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostResponsesInputItemsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/responses/compact": { "post": { "operationId": "openaiCreateCompaction", "summary": "Compact context (OpenAI)", "description": "Compresses a conversation into an opaque compaction item using the OpenAI-compatible\n`/v1/responses/compact` endpoint. Drop-in compatible with the OpenAI SDK.\n\nThe response `output` contains the user messages plus a final item with\n`type: \"response.compaction\"` and `encrypted_content`. Pass this output as `input`\nto future Responses API calls to continue the conversation using the compacted context.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/responses/compact`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model identifier (e.g., \"gpt-4o\"). When routing through Bifrost's provider-prefixed path, use \"provider/model\" format.\n" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } } ], "description": "Conversation to compact. Required unless previous_response_id is set. Compaction items (type \"response.compaction\") from prior responses may be included.\n" }, "instructions": { "type": "string", "description": "System instructions that persist across the compacted context." }, "previous_response_id": { "type": "string", "description": "ID of a previous response to extend rather than sending full input." }, "prompt_cache_key": { "type": "string" }, "prompt_cache_retention": { "type": "string" }, "service_tier": { "type": "string" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Bifrost-specific — fallback model list in provider/model format." } } } } } }, "responses": { "200": { "description": "Successful compaction response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "description": "Always \"response.compaction\"", "example": "response.compaction" }, "model": { "type": "string" }, "created_at": { "type": "integer" }, "output": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "description": "The compacted output — the original user messages plus a final item of type \"response.compaction\" whose encrypted_content holds the opaque compacted state. Pass the full output array as input to a future Responses API request.\n" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "input_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "image_tokens": { "type": "integer" }, "cached_read_tokens": { "type": "integer", "description": "Tokens served from the prompt cache (cache hit), billed at the reduced cache-read rate. Already included in the parent input_tokens total.\n" }, "cached_write_tokens": { "type": "integer", "description": "Tokens written to the prompt cache on this request, billed at the cache-creation rate. Already included in the parent input_tokens total. Populated for providers that separately report cache write tokens (Anthropic, Bedrock).\n" } } }, "output_tokens": { "type": "integer" }, "output_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "accepted_prediction_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "rejected_prediction_tokens": { "type": "integer" }, "citation_tokens": { "type": "integer" }, "num_search_queries": { "type": "integer" } } }, "total_tokens": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/BifrostCost" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/embeddings": { "post": { "operationId": "openaiCreateEmbedding", "summary": "Create embeddings (OpenAI format)", "description": "Creates embedding vectors for the input text.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/embeddings`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/openai/deployments/{deployment-id}/embeddings": { "post": { "operationId": "azureCreateEmbedding", "summary": "Create embeddings (Azure OpenAI)", "tags": [ "OpenAI Integration", "Azure Integration" ], "parameters": [ { "name": "deployment-id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Azure deployment ID" }, { "name": "api-version", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/audio/speech": { "post": { "operationId": "openaiCreateSpeech", "summary": "Create speech (OpenAI TTS)", "description": "Generates audio from text using OpenAI TTS.\nSupports streaming via SSE when stream_format is set to 'sse'.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/audio/speech`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAISpeechRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/opus": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "speech.audio.delta", "speech.audio.done" ] }, "audio": { "type": "string", "format": "byte" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/openai/deployments/{deployment-id}/audio/speech": { "post": { "operationId": "azureCreateSpeech", "summary": "Create speech (Azure OpenAI TTS)", "tags": [ "OpenAI Integration", "Azure Integration" ], "parameters": [ { "name": "deployment-id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Azure deployment ID" }, { "name": "api-version", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAISpeechRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/opus": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "speech.audio.delta", "speech.audio.done" ] }, "audio": { "type": "string", "format": "byte" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/audio/transcriptions": { "post": { "operationId": "openaiCreateTranscription", "summary": "Create transcription (OpenAI Whisper)", "description": "Transcribes audio into text using OpenAI Whisper.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/audio/transcriptions`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OpenAITranscriptionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transcript.text.delta", "transcript.text.done" ] }, "delta": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" } } } } }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tokens", "duration" ] }, "input_tokens": { "type": "integer" }, "input_token_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "seconds": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/openai/deployments/{deployment-id}/audio/transcriptions": { "post": { "operationId": "azureCreateTranscription", "summary": "Create transcription (Azure OpenAI)", "tags": [ "OpenAI Integration", "Azure Integration" ], "parameters": [ { "name": "deployment-id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Azure deployment ID" }, { "name": "api-version", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OpenAITranscriptionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transcript.text.delta", "transcript.text.done" ] }, "delta": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" } } } } }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tokens", "duration" ] }, "input_tokens": { "type": "integer" }, "input_token_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "seconds": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/models": { "get": { "operationId": "openaiListModels", "summary": "List models (OpenAI format)", "description": "Lists available models in OpenAI format.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/models`).\n", "tags": [ "OpenAI Integration" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/openai/deployments/{deployment-id}/models": { "get": { "operationId": "azureListModels", "summary": "List models (Azure OpenAI)", "tags": [ "OpenAI Integration", "Azure Integration" ], "parameters": [ { "name": "deployment-id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Azure deployment ID" }, { "name": "api-version", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/batches": { "post": { "operationId": "openaiCreateBatch", "summary": "Create batch job (OpenAI format)", "description": "Creates a batch processing job.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/batches`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "openaiListBatches", "summary": "List batch jobs (OpenAI format)", "description": "Lists batch processing jobs.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/batches`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 }, "description": "Maximum number of batches to return" }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Filter by provider" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/batches/{batch_id}": { "get": { "operationId": "openaiRetrieveBatch", "summary": "Retrieve batch job (OpenAI format)", "description": "Retrieves details of a batch processing job.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/batches/{batch_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch job ID" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the batch" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRetrieveResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/batches/{batch_id}/cancel": { "post": { "operationId": "openaiCancelBatch", "summary": "Cancel batch job (OpenAI format)", "description": "Cancels a batch processing job.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/batches/{batch_id}/cancel`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch job ID to cancel" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the batch" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string", "enum": [ "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "canceled", "ended" ] }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "succeeded": { "type": "integer" }, "expired": { "type": "integer" }, "canceled": { "type": "integer" }, "pending": { "type": "integer" } } }, "cancelling_at": { "type": "integer", "format": "int64" }, "cancelled_at": { "type": "integer", "format": "int64" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/images/generations": { "post": { "operationId": "openaiCreateImage", "summary": "Create image", "description": "Generates images from text prompts using OpenAI-compatible format.\n\n**Note:** Azure OpenAI deployments are also supported via the Azure integration endpoint.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/images/generations`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model identifier" }, "prompt": { "type": "string", "description": "Text prompt to generate image" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Number of images to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the generated image" }, "quality": { "type": "string", "enum": [ "standard", "hd" ], "description": "Quality of the generated image" }, "style": { "type": "string", "enum": [ "natural", "vivid" ], "description": "Style of the generated image" }, "response_format": { "type": "string", "enum": [ "url", "b64_json" ], "default": "url", "description": "Format of the response. This parameter is not supported for streaming requests." }, "user": { "type": "string", "description": "User identifier for tracking" }, "stream": { "type": "boolean", "default": false, "description": "Whether to stream the response. When true, images are sent as base64 chunks via SSE.\n" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback models to try if primary model fails" } } } } } }, "responses": { "200": { "description": "Successful response. Returns JSON for non-streaming requests, or Server-Sent Events (SSE) stream when `stream=true`.\nWhen streaming, each event contains a chunk of the image as base64 data, with the final event having type `image_generation.completed`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer", "format": "int64", "description": "Unix timestamp when the image was created" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-side asset identifier, when one is assigned. Providers that accept their own\nasset IDs as inputs (e.g. Runware) allow this to be fed straight into a follow-up task.\n" }, "url": { "type": "string", "format": "uri", "description": "URL of the generated image" }, "b64_json": { "type": "string", "description": "Base64-encoded image data" }, "revised_prompt": { "type": "string", "description": "Revised prompt used for generation" }, "index": { "type": "integer", "description": "Index of this image" }, "detections": { "type": "array", "items": { "type": "object", "description": "A region located by a masking model, in absolute input-image pixels", "properties": { "x_min": { "type": "integer" }, "y_min": { "type": "integer" }, "x_max": { "type": "integer" }, "y_max": { "type": "integer" } } }, "description": "Regions located by a masking or segmentation operation" } } }, "description": "Array of generated images" }, "background": { "type": "string", "description": "Background type used" }, "output_format": { "type": "string", "description": "Output format used" }, "quality": { "type": "string", "description": "Quality setting used" }, "size": { "type": "string", "description": "Size setting used" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } } } } } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming response chunk for image generation (OpenAI format).\nSent via Server-Sent Events (SSE) when stream=true.\n", "properties": { "type": { "type": "string", "enum": [ "image_generation.partial_image", "image_generation.completed", "error" ], "description": "Type of stream event" }, "b64_json": { "type": "string", "description": "Base64-encoded chunk of image data" }, "partial_image_index": { "type": "integer", "description": "Index of the partial image chunk" }, "sequence_number": { "type": "integer", "description": "Ordering index for stream chunks" }, "created_at": { "type": "integer", "format": "int64", "description": "Timestamp when chunk was created" }, "size": { "type": "string", "description": "Size of the generated image" }, "quality": { "type": "string", "description": "Quality setting used" }, "background": { "type": "string", "description": "Background type used" }, "output_format": { "type": "string", "description": "Output format used" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } }, "description": "Token usage (usually in final chunk)" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/openai/deployments/{deployment-id}/images/generations": { "post": { "operationId": "azureCreateImage", "summary": "Create image (Azure OpenAI)", "description": "Generates images from text prompts using Azure OpenAI deployment.\n", "tags": [ "OpenAI Integration", "Azure Integration" ], "parameters": [ { "name": "deployment-id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Azure deployment ID" }, { "name": "api-version", "in": "query", "schema": { "type": "string" }, "description": "Azure API version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model identifier" }, "prompt": { "type": "string", "description": "Text prompt to generate image" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Number of images to generate" }, "size": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792", "1536x1024", "1024x1536", "auto" ], "description": "Size of the generated image" }, "quality": { "type": "string", "enum": [ "standard", "hd" ], "description": "Quality of the generated image" }, "style": { "type": "string", "enum": [ "natural", "vivid" ], "description": "Style of the generated image" }, "response_format": { "type": "string", "enum": [ "url", "b64_json" ], "default": "url", "description": "Format of the response. This parameter is not supported for streaming requests." }, "user": { "type": "string", "description": "User identifier for tracking" }, "stream": { "type": "boolean", "default": false, "description": "Whether to stream the response. When true, images are sent as base64 chunks via SSE.\n" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback models to try if primary model fails" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer", "format": "int64", "description": "Unix timestamp when the image was created" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-side asset identifier, when one is assigned. Providers that accept their own\nasset IDs as inputs (e.g. Runware) allow this to be fed straight into a follow-up task.\n" }, "url": { "type": "string", "format": "uri", "description": "URL of the generated image" }, "b64_json": { "type": "string", "description": "Base64-encoded image data" }, "revised_prompt": { "type": "string", "description": "Revised prompt used for generation" }, "index": { "type": "integer", "description": "Index of this image" }, "detections": { "type": "array", "items": { "type": "object", "description": "A region located by a masking model, in absolute input-image pixels", "properties": { "x_min": { "type": "integer" }, "y_min": { "type": "integer" }, "x_max": { "type": "integer" }, "y_max": { "type": "integer" } } }, "description": "Regions located by a masking or segmentation operation" } } }, "description": "Array of generated images" }, "background": { "type": "string", "description": "Background type used" }, "output_format": { "type": "string", "description": "Output format used" }, "quality": { "type": "string", "description": "Quality setting used" }, "size": { "type": "string", "description": "Size setting used" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } } } } } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming response chunk for image generation (OpenAI format).\nSent via Server-Sent Events (SSE) when stream=true.\n", "properties": { "type": { "type": "string", "enum": [ "image_generation.partial_image", "image_generation.completed", "error" ], "description": "Type of stream event" }, "b64_json": { "type": "string", "description": "Base64-encoded chunk of image data" }, "partial_image_index": { "type": "integer", "description": "Index of the partial image chunk" }, "sequence_number": { "type": "integer", "description": "Ordering index for stream chunks" }, "created_at": { "type": "integer", "format": "int64", "description": "Timestamp when chunk was created" }, "size": { "type": "string", "description": "Size of the generated image" }, "quality": { "type": "string", "description": "Quality setting used" }, "background": { "type": "string", "description": "Background type used" }, "output_format": { "type": "string", "description": "Output format used" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" }, "input_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens" }, "output_tokens_details": { "type": "object", "properties": { "image_tokens": { "type": "integer", "description": "Tokens used for images" }, "text_tokens": { "type": "integer", "description": "Tokens used for text" } } } }, "description": "Token usage (usually in final chunk)" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/files": { "post": { "operationId": "openaiUploadFile", "summary": "Upload file (OpenAI format)", "description": "Uploads a file for use with batch processing or other features.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/files`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "purpose" ], "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload" }, "purpose": { "type": "string", "enum": [ "assistants", "assistants_output", "batch", "batch_output", "fine-tune", "fine-tune-results", "vision", "user_data", "evals" ], "description": "Purpose of the file" }, "provider": { "type": "string", "description": "Provider for file storage" }, "storage_config": { "type": "object", "description": "Storage configuration for cloud storage backends", "properties": { "s3": { "type": "object", "description": "AWS S3 storage configuration", "properties": { "bucket": { "type": "string", "description": "S3 bucket name" }, "region": { "type": "string", "description": "AWS region" }, "prefix": { "type": "string", "description": "Path prefix for stored files" } } }, "gcs": { "type": "object", "description": "Google Cloud Storage configuration", "properties": { "bucket": { "type": "string", "description": "GCS bucket name" }, "project": { "type": "string", "description": "GCP project ID" }, "prefix": { "type": "string", "description": "Path prefix for stored files" } } } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "openaiListFiles", "summary": "List files (OpenAI format)", "description": "Lists uploaded files.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/files`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "purpose", "in": "query", "schema": { "type": "string" }, "description": "Filter by purpose" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Maximum files to return" }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Filter by provider" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/files/{file_id}": { "get": { "operationId": "openaiRetrieveFile", "summary": "Retrieve file metadata (OpenAI format)", "description": "Retrieves metadata for an uploaded file.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/files/{file_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the file" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "integer", "format": "int64" }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "batch", "assistants", "fine-tune", "vision", "batch_output", "user_data", "responses", "evals" ] }, "status": { "type": "string", "enum": [ "uploaded", "processed", "processing", "error", "deleted" ] }, "status_details": { "type": "string" }, "expires_at": { "type": "integer", "format": "int64" }, "storage_backend": { "type": "string" }, "storage_uri": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "openaiDeleteFile", "summary": "Delete file (OpenAI format)", "description": "Deletes an uploaded file.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/files/{file_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID to delete" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the file" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/files/{file_id}/content": { "get": { "operationId": "openaiGetFileContent", "summary": "Get file content (OpenAI format)", "description": "Retrieves the content of an uploaded file.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/files/{file_id}/content`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the file" } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/containers": { "post": { "operationId": "openaiCreateContainer", "summary": "Create container (OpenAI format)", "description": "Creates a new container for storing files and data.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers`).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "name" ], "properties": { "provider": { "$ref": "#/components/schemas/ModelProvider" }, "name": { "type": "string", "description": "Name of the container" }, "expires_after": { "type": "object", "description": "Expiration configuration for a container", "properties": { "anchor": { "type": "string", "description": "The anchor point for expiration (e.g., \"last_active_at\")" }, "minutes": { "type": "integer", "description": "Number of minutes after anchor point" } } }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of existing files to copy into this container" }, "memory_limit": { "type": "string", "description": "Memory limit for the container (e.g., \"1g\", \"4g\")" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User-provided metadata" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the created container" }, "object": { "type": "string", "description": "The object type (always \"container\")" }, "name": { "type": "string", "description": "The name of the container" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the container was created" }, "status": { "type": "string", "enum": [ "running" ], "description": "The status of a container" }, "expires_after": { "type": "object", "description": "Expiration configuration for a container", "properties": { "anchor": { "type": "string", "description": "The anchor point for expiration (e.g., \"last_active_at\")" }, "minutes": { "type": "integer", "description": "Number of minutes after anchor point" } } }, "last_active_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of last activity" }, "memory_limit": { "type": "string", "description": "Memory limit for the container" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User-provided metadata" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "openaiListContainers", "summary": "List containers (OpenAI format)", "description": "Lists containers for a provider.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider to list containers for (defaults to openai)" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Maximum containers to return" }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort order" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type (always \"list\")" }, "data": { "type": "array", "items": { "type": "object", "description": "A container object", "properties": { "id": { "type": "string", "description": "The unique identifier for the container" }, "object": { "type": "string", "description": "The object type (always \"container\")" }, "name": { "type": "string", "description": "The name of the container" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the container was created" }, "status": { "type": "string", "enum": [ "running" ], "description": "The status of a container" }, "expires_after": { "type": "object", "description": "Expiration configuration for a container", "properties": { "anchor": { "type": "string", "description": "The anchor point for expiration (e.g., \"last_active_at\")" }, "minutes": { "type": "integer", "description": "Number of minutes after anchor point" } } }, "last_active_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of last activity" }, "memory_limit": { "type": "string", "description": "Memory limit for the container (e.g., \"1g\", \"4g\")" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User-provided metadata" } } }, "description": "List of container objects" }, "first_id": { "type": "string", "description": "ID of the first container in the list" }, "last_id": { "type": "string", "description": "ID of the last container in the list" }, "has_more": { "type": "boolean", "description": "Whether there are more containers to fetch" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/containers/{container_id}": { "get": { "operationId": "openaiRetrieveContainer", "summary": "Retrieve container (OpenAI format)", "description": "Retrieves a specific container by ID.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers/{container_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Container ID" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the container (defaults to openai)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the container" }, "object": { "type": "string", "description": "The object type (always \"container\")" }, "name": { "type": "string", "description": "The name of the container" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the container was created" }, "status": { "type": "string", "enum": [ "running" ], "description": "The status of a container" }, "expires_after": { "type": "object", "description": "Expiration configuration for a container", "properties": { "anchor": { "type": "string", "description": "The anchor point for expiration (e.g., \"last_active_at\")" }, "minutes": { "type": "integer", "description": "Number of minutes after anchor point" } } }, "last_active_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of last activity" }, "memory_limit": { "type": "string", "description": "Memory limit for the container" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User-provided metadata" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "openaiDeleteContainer", "summary": "Delete container (OpenAI format)", "description": "Deletes a container.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers/{container_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Container ID to delete" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the container (defaults to openai)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the deleted container" }, "object": { "type": "string", "description": "The object type (always \"container.deleted\")" }, "deleted": { "type": "boolean", "description": "Whether the container was successfully deleted" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/containers/{container_id}/files": { "post": { "operationId": "openaiCreateContainerFile", "summary": "Create file in container (OpenAI format)", "description": "Creates a new file in a container. You can either upload file content directly\nvia multipart/form-data or reference an existing file by its ID.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers/{container_id}/files`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Container ID" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the container (defaults to openai)" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Request to create a file in a container via multipart upload", "properties": { "file": { "type": "string", "format": "binary", "description": "The file content to upload" }, "file_path": { "type": "string", "description": "Optional path for the file within the container" } } } }, "application/json": { "schema": { "type": "object", "description": "Request to create a file in a container by referencing an existing file", "required": [ "file_id" ], "properties": { "file_id": { "type": "string", "description": "The ID of an existing file to copy into the container" }, "file_path": { "type": "string", "description": "Optional path for the file within the container" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Response from creating a file in a container", "properties": { "id": { "type": "string", "description": "The unique identifier for the created file" }, "object": { "type": "string", "description": "The object type (always \"container.file\")" }, "container_id": { "type": "string", "description": "The ID of the container this file belongs to" }, "path": { "type": "string", "description": "The path of the file within the container" }, "bytes": { "type": "integer", "format": "int64", "description": "The size of the file in bytes" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the file was created" }, "source": { "type": "string", "description": "The source of the file" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "openaiListContainerFiles", "summary": "List files in container (OpenAI format)", "description": "Lists all files in a container.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers/{container_id}/files`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Container ID" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the container (defaults to openai)" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Maximum files to return" }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort order" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Response containing a list of files in a container", "properties": { "object": { "type": "string", "description": "The object type (always \"list\")" }, "data": { "type": "array", "items": { "type": "object", "description": "A file object within a container", "properties": { "id": { "type": "string", "description": "The unique identifier for the file" }, "object": { "type": "string", "description": "The object type (always \"container.file\")" }, "container_id": { "type": "string", "description": "The ID of the container this file belongs to" }, "path": { "type": "string", "description": "The path of the file within the container" }, "bytes": { "type": "integer", "format": "int64", "description": "The size of the file in bytes" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the file was created" }, "source": { "type": "string", "description": "The source of the file (e.g., \"user_upload\", \"copied\")" } } }, "description": "List of file objects" }, "first_id": { "type": "string", "description": "ID of the first file in the list" }, "last_id": { "type": "string", "description": "ID of the last file in the list" }, "has_more": { "type": "boolean", "description": "Whether there are more files to fetch" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/containers/{container_id}/files/{file_id}": { "get": { "operationId": "openaiRetrieveContainerFile", "summary": "Retrieve file from container (OpenAI format)", "description": "Retrieves metadata for a specific file in a container.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers/{container_id}/files/{file_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Container ID" }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the container (defaults to openai)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Response from retrieving a file from a container", "properties": { "id": { "type": "string", "description": "The unique identifier for the file" }, "object": { "type": "string", "description": "The object type (always \"container.file\")" }, "container_id": { "type": "string", "description": "The ID of the container this file belongs to" }, "path": { "type": "string", "description": "The path of the file within the container" }, "bytes": { "type": "integer", "format": "int64", "description": "The size of the file in bytes" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the file was created" }, "source": { "type": "string", "description": "The source of the file" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "openaiDeleteContainerFile", "summary": "Delete file from container (OpenAI format)", "description": "Deletes a file from a container.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers/{container_id}/files/{file_id}`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Container ID" }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID to delete" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the container (defaults to openai)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Response from deleting a file from a container", "properties": { "id": { "type": "string", "description": "The ID of the deleted file" }, "object": { "type": "string", "description": "The object type (always \"container.file.deleted\")" }, "deleted": { "type": "boolean", "description": "Whether the file was successfully deleted" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/containers/{container_id}/files/{file_id}/content": { "get": { "operationId": "openaiGetContainerFileContent", "summary": "Get file content from container (OpenAI format)", "description": "Downloads the content of a file from a container.\n\n**Note:** This endpoint also works without the `/v1` prefix (e.g., `/openai/containers/{container_id}/files/{file_id}/content`).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Container ID" }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider for the container (defaults to openai)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/videos": { "post": { "operationId": "openaiCreateVideo", "summary": "Create a video generation", "description": "Submits a video generation job using OpenAI's Videos API.\nThe request is multipart/form-data and may include reference images.\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "prompt", "model" ], "properties": { "model": { "type": "string", "description": "Video model identifier (e.g. `sora-1.0`)." }, "prompt": { "type": "string", "description": "Natural-language description of the requested video." }, "size": { "type": "string", "description": "Output resolution (e.g. `1024x1024`)." }, "seconds": { "type": "integer", "description": "Target duration in seconds." }, "input_reference": { "type": "string", "format": "binary", "description": "Optional reference image used to seed generation." } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "OpenAI video generation job payload." } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "openaiListVideos", "summary": "List video generations", "description": "Lists previously submitted video generation jobs.", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "OpenAI video list payload." } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/videos/{video_id}": { "get": { "operationId": "openaiRetrieveVideo", "summary": "Retrieve a video generation", "description": "Returns metadata for a previously submitted video generation job.", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Video not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "openaiDeleteVideo", "summary": "Delete a video generation", "description": "Deletes a previously generated video.", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Video not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/videos/{video_id}/content": { "get": { "operationId": "openaiDownloadVideo", "summary": "Download generated video content", "description": "Streams the binary video bytes for a completed generation job.", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw video bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Video not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/videos/{video_id}/remix": { "post": { "operationId": "openaiRemixVideo", "summary": "Remix an existing video", "description": "Creates a new generation by remixing a prior video with new prompt parameters.", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "OpenAI video-remix request payload." } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/realtime": { "get": { "operationId": "openaiRealtimeWebSocket", "summary": "WebSocket Realtime (OpenAI alias)", "description": "OpenAI-prefixed alias of `GET /v1/realtime`. WebSocket upgrade endpoint\nfor OpenAI Realtime; selects the model via the `model` query parameter\n(Azure GA) or `deployment` (preview).\n", "tags": [ "OpenAI Integration" ], "parameters": [ { "name": "model", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "deployment", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "Upgrade", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "websocket" ] } }, { "name": "Sec-WebSocket-Protocol", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "101": { "description": "WebSocket connection established." }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "401": { "description": "Unauthorized." } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/realtime/calls": { "post": { "operationId": "openaiRealtimeCall", "summary": "WebRTC Realtime SDP exchange (OpenAI alias)", "description": "OpenAI-prefixed alias of `POST /v1/realtime/calls`. Performs the WebRTC\nSDP exchange for OpenAI Realtime calls. Accepts either multipart form\ndata with `sdp` + `session` parts (GA) or a raw SDP body (legacy).\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "sdp": { "type": "string", "description": "WebRTC offer SDP." }, "session": { "type": "string", "description": "JSON-encoded session configuration." } } } }, "application/sdp": { "schema": { "type": "string", "description": "Raw WebRTC offer SDP (legacy form)." } } } }, "responses": { "200": { "description": "WebRTC answer SDP.", "content": { "application/sdp": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/realtime/client_secrets": { "post": { "operationId": "openaiRealtimeClientSecret", "summary": "Create realtime client secret (OpenAI alias)", "description": "OpenAI-prefixed alias of `POST /v1/realtime/client_secrets`. Mints an\nephemeral client secret used to authorize a downstream Realtime client.\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "OpenAI client-secret request payload." } } } }, "responses": { "200": { "description": "Ephemeral client secret payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/openai/v1/realtime/sessions": { "post": { "operationId": "openaiRealtimeSession", "summary": "Create realtime session (OpenAI alias)", "description": "OpenAI-prefixed alias of `POST /v1/realtime/sessions`. Creates a\npre-configured realtime session that can be joined by clients.\n", "tags": [ "OpenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "OpenAI realtime session configuration." } } } }, "responses": { "200": { "description": "Realtime session payload.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/messages": { "post": { "operationId": "anthropicCreateMessage", "summary": "Create message (Anthropic format)", "description": "Creates a message using Anthropic Messages API format.\nSupports streaming via SSE.\n\n**Async inference:** Send `x-bf-async: true` to submit the request as a background job and receive a job ID immediately. Poll with `x-bf-async-id: ` to retrieve the result. When the job is still processing, the response will have an empty `content` array. When completed, `content` will contain the full result. See [Async Inference](/features/async-inference) for details.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "x-bf-async", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Set to `true` to submit this request as an async job. Returns immediately with a job ID. Not compatible with streaming." }, { "name": "x-bf-async-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Poll for results of a previously submitted async job by providing the job ID returned from the initial async request." }, { "name": "x-bf-async-job-result-ttl", "in": "header", "required": false, "schema": { "type": "integer", "default": 3600 }, "description": "Override the default result TTL in seconds. Results expire after this duration from completion time." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message_start", "content_block_start", "content_block_delta", "content_block_stop", "message_delta", "message_stop", "ping", "error" ] }, "message": { "$ref": "#/components/schemas/AnthropicMessageResponse" }, "index": { "type": "integer" }, "content_block": { "$ref": "#/components/schemas/AnthropicContentBlock" }, "delta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_delta", "input_json_delta", "thinking_delta", "signature_delta" ] }, "text": { "type": "string" }, "partial_json": { "type": "string" }, "thinking": { "type": "string" }, "signature": { "type": "string" }, "stop_reason": { "type": "string" }, "stop_sequence": { "type": "string" } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" }, "cache_creation": { "type": "object", "properties": { "ephemeral_5m_input_tokens": { "type": "integer" }, "ephemeral_1h_input_tokens": { "type": "integer" } } } } }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/messages/{path}": { "post": { "operationId": "anthropicCreateMessageWildcard", "summary": "Create message (Anthropic format) - wildcard", "description": "Handles extended messages API paths.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Extended path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message_start", "content_block_start", "content_block_delta", "content_block_stop", "message_delta", "message_stop", "ping", "error" ] }, "message": { "$ref": "#/components/schemas/AnthropicMessageResponse" }, "index": { "type": "integer" }, "content_block": { "$ref": "#/components/schemas/AnthropicContentBlock" }, "delta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_delta", "input_json_delta", "thinking_delta", "signature_delta" ] }, "text": { "type": "string" }, "partial_json": { "type": "string" }, "thinking": { "type": "string" }, "signature": { "type": "string" }, "stop_reason": { "type": "string" }, "stop_sequence": { "type": "string" } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" }, "cache_creation": { "type": "object", "properties": { "ephemeral_5m_input_tokens": { "type": "integer" }, "ephemeral_1h_input_tokens": { "type": "integer" } } } } }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/complete": { "post": { "operationId": "anthropicCreateComplete", "summary": "Create completion (Anthropic legacy format)", "description": "Creates a text completion using Anthropic's legacy Complete API.\nSupports streaming via SSE.\n", "tags": [ "Anthropic Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicTextRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "completion" }, "id": { "type": "string" }, "completion": { "type": "string" }, "stop_reason": { "type": "string", "enum": [ "stop_sequence", "max_tokens", null ] }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens generated" } } } } } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "completion" }, "id": { "type": "string" }, "completion": { "type": "string" }, "stop_reason": { "type": "string", "enum": [ "stop_sequence", "max_tokens", null ] }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens generated" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/models": { "get": { "operationId": "anthropicListModels", "summary": "List models (Anthropic format)", "description": "Lists available models in Anthropic format.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Maximum number of models to return" }, { "name": "before_id", "in": "query", "schema": { "type": "string" }, "description": "Return models before this ID" }, { "name": "after_id", "in": "query", "schema": { "type": "string" }, "description": "Return models after this ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/messages/count_tokens": { "post": { "operationId": "anthropicCountTokens", "summary": "Count tokens (Anthropic format)", "description": "Counts the number of tokens in a message request.\n", "tags": [ "Anthropic Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AnthropicMessageRequest" } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/messages/batches": { "post": { "operationId": "anthropicCreateBatch", "summary": "Create batch job (Anthropic format)", "description": "Creates a batch processing job using Anthropic format.\nUse x-model-provider header to specify the provider.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider to use (defaults to anthropic)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "requests" ], "properties": { "requests": { "type": "array", "items": { "type": "object", "required": [ "custom_id", "params" ], "properties": { "custom_id": { "type": "string", "description": "Unique identifier for this request" }, "params": { "type": "object", "description": "Request parameters (same as AnthropicMessageRequest)" } } }, "description": "Array of batch request items" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "message_batch" }, "processing_status": { "type": "string", "enum": [ "in_progress", "ended", "canceling" ] }, "request_counts": { "type": "object", "properties": { "processing": { "type": "integer" }, "succeeded": { "type": "integer" }, "errored": { "type": "integer" }, "canceled": { "type": "integer" }, "expired": { "type": "integer" } } }, "ended_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "cancel_initiated_at": { "type": "string", "format": "date-time", "nullable": true }, "results_url": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "anthropicListBatches", "summary": "List batch jobs (Anthropic format)", "description": "Lists batch processing jobs.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider to use (defaults to anthropic)" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "Maximum number of batches to return" }, { "name": "page_token", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "message_batch" }, "processing_status": { "type": "string", "enum": [ "in_progress", "ended", "canceling" ] }, "request_counts": { "type": "object", "properties": { "processing": { "type": "integer" }, "succeeded": { "type": "integer" }, "errored": { "type": "integer" }, "canceled": { "type": "integer" }, "expired": { "type": "integer" } } }, "ended_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "cancel_initiated_at": { "type": "string", "format": "date-time", "nullable": true }, "results_url": { "type": "string", "nullable": true } } } }, "has_more": { "type": "boolean" }, "first_id": { "type": "string" }, "last_id": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/messages/batches/{batch_id}": { "get": { "operationId": "anthropicRetrieveBatch", "summary": "Retrieve batch job (Anthropic format)", "description": "Retrieves details of a batch processing job.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch job ID" }, { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider for the batch" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "message_batch" }, "processing_status": { "type": "string", "enum": [ "in_progress", "ended", "canceling" ] }, "request_counts": { "type": "object", "properties": { "processing": { "type": "integer" }, "succeeded": { "type": "integer" }, "errored": { "type": "integer" }, "canceled": { "type": "integer" }, "expired": { "type": "integer" } } }, "ended_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "cancel_initiated_at": { "type": "string", "format": "date-time", "nullable": true }, "results_url": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/messages/batches/{batch_id}/cancel": { "post": { "operationId": "anthropicCancelBatch", "summary": "Cancel batch job (Anthropic format)", "description": "Cancels a batch processing job.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch job ID to cancel" }, { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider for the batch" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "message_batch" }, "processing_status": { "type": "string", "enum": [ "in_progress", "ended", "canceling" ] }, "request_counts": { "type": "object", "properties": { "processing": { "type": "integer" }, "succeeded": { "type": "integer" }, "errored": { "type": "integer" }, "canceled": { "type": "integer" }, "expired": { "type": "integer" } } }, "ended_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "cancel_initiated_at": { "type": "string", "format": "date-time", "nullable": true }, "results_url": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/messages/batches/{batch_id}/results": { "get": { "operationId": "anthropicGetBatchResults", "summary": "Get batch results (Anthropic format)", "description": "Retrieves results of a completed batch job.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch job ID" }, { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider for the batch" } ], "responses": { "200": { "description": "Successful response (JSONL stream)", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/files": { "post": { "operationId": "anthropicUploadFile", "summary": "Upload file (Anthropic format)", "description": "Uploads a file. Use x-model-provider header to specify the provider.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider to use (defaults to anthropic)" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload (raw file content)" }, "filename": { "type": "string", "description": "Original filename" }, "purpose": { "type": "string", "description": "Purpose of the file (e.g., \"batch\")" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "file" }, "filename": { "type": "string" }, "mime_type": { "type": "string", "description": "MIME type of the file" }, "size_bytes": { "type": "integer", "description": "Size of the file in bytes" }, "created_at": { "type": "string", "format": "date-time" }, "downloadable": { "type": "boolean" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "anthropicListFiles", "summary": "List files (Anthropic format)", "description": "Lists uploaded files.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider to use (defaults to anthropic)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 }, "description": "Maximum files to return" }, { "name": "after_id", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "file" }, "filename": { "type": "string" }, "mime_type": { "type": "string", "description": "MIME type of the file" }, "size_bytes": { "type": "integer", "description": "Size of the file in bytes" }, "created_at": { "type": "string", "format": "date-time" }, "downloadable": { "type": "boolean" } } } }, "has_more": { "type": "boolean" }, "first_id": { "type": "string" }, "last_id": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/files/{file_id}/content": { "get": { "operationId": "anthropicGetFileContent", "summary": "Get file content (Anthropic format)", "description": "Retrieves file content. Returns raw binary file data when Accept header is set to application/octet-stream,\nor file metadata as JSON when Accept header is set to application/json.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID" }, { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider for the file" }, { "name": "Accept", "in": "header", "schema": { "type": "string", "enum": [ "application/json", "application/octet-stream" ], "default": "application/json" }, "description": "Response content type - use application/octet-stream for binary download" } ], "responses": { "200": { "description": "Successful response. Returns file metadata as JSON or raw binary file content.\nWhen returning binary content, the Content-Type header indicates the file's MIME type\nand Content-Disposition header may include the filename.\n", "headers": { "Content-Type": { "schema": { "type": "string" }, "description": "MIME type of the file (e.g., application/pdf, image/png, text/plain)" }, "Content-Disposition": { "schema": { "type": "string" }, "description": "Attachment filename directive (e.g., attachment; filename=\"document.pdf\")" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "file" }, "filename": { "type": "string" }, "mime_type": { "type": "string", "description": "MIME type of the file" }, "size_bytes": { "type": "integer", "description": "Size of the file in bytes" }, "created_at": { "type": "string", "format": "date-time" }, "downloadable": { "type": "boolean" } } } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw binary file content" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/anthropic/v1/files/{file_id}": { "delete": { "operationId": "anthropicDeleteFile", "summary": "Delete file (Anthropic format)", "description": "Deletes an uploaded file.\n", "tags": [ "Anthropic Integration" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID to delete" }, { "name": "x-model-provider", "in": "header", "schema": { "type": "string" }, "description": "Provider for the file" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "file_deleted" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/models/{model}:generateContent": { "post": { "operationId": "geminiGenerateContent", "summary": "Generate content (Gemini format)", "description": "Generates content using Google Gemini API format.\nThe model is specified in the URL path.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action (e.g., gemini-pro:generateContent)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/models/{model}:streamGenerateContent": { "post": { "operationId": "geminiStreamGenerateContent", "summary": "Stream generate content (Gemini format)", "description": "Streams content generation using Google Gemini API format.\nThe model is specified in the URL path.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action (e.g., gemini-pro:streamGenerateContent)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/models/{model}:embedContent": { "post": { "operationId": "geminiEmbedContent", "summary": "Embed content (Gemini format)", "description": "Creates embeddings using Google Gemini API format.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action (e.g., embedding-001:embedContent)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiEmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/models/{model}:countTokens": { "post": { "operationId": "geminiCountTokens", "summary": "Count tokens (Gemini format)", "description": "Counts tokens using Google Gemini API format.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action (e.g., gemini-pro:countTokens)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contents": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiContent" } }, "generateContentRequest": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalTokens": { "type": "integer", "description": "Number of tokens that the model tokenizes the prompt into" }, "cachedContentTokenCount": { "type": "integer", "description": "Number of tokens in the cached part of the prompt" }, "promptTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "description": "The modality (TEXT, IMAGE, AUDIO, etc.)" }, "tokenCount": { "type": "integer" } } }, "description": "Modalities processed in the request input" }, "cacheTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "description": "The modality (TEXT, IMAGE, AUDIO, etc.)" }, "tokenCount": { "type": "integer" } } }, "description": "Modalities in the cached content" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/models/{model}:predict": { "post": { "operationId": "geminiGenerateImage", "summary": "Generate image (Gemini format)", "description": "For Imagen models, use the `:predict` suffix (e.g., `imagen-3.0-generate-001:predict`).\nFor Gemini models, use `:generateContent` with `generationConfig.responseModalities: [\"IMAGE\"]` in the request body.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action suffix. For Imagen models, use `:predict` (e.g., `imagen-3.0-generate-001:predict`).\nFor Gemini models with image generation, use `:generateContent` (e.g., `gemini-1.5-pro:generateContent`).\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response. Returns JSON with generated image data in `candidates[0].content.parts[0].inlineData`.\nWhen streaming, events are sent via Server-Sent Events (SSE).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/models": { "get": { "operationId": "geminiListModels", "summary": "List models (Gemini format)", "description": "Lists available models in Google Gemini API format.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "pageSize", "in": "query", "schema": { "type": "integer" }, "description": "Maximum number of models to return" }, { "name": "pageToken", "in": "query", "schema": { "type": "string" }, "description": "Page token for pagination" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/upload/v1beta/files": { "post": { "operationId": "geminiUploadFile", "summary": "Upload file (Gemini format)", "description": "Uploads a file using Google Gemini API format.\n\nThis is a multipart upload with two parts:\n- \"metadata\": JSON object containing file metadata\n- \"file\": Binary file content\n\nNote: Direct file content download is not supported by Gemini Files API.\nUse the file.uri field from the response to access uploaded files.\n", "tags": [ "GenAI Integration" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Multipart upload for Gemini Files API. Send two parts: - \"metadata\": JSON object {\"file\": {\"displayName\": \"\"}} - \"file\": binary content Note: Direct file content download is not supported by Gemini Files API. Use the file.uri field from the response to access the file.\n", "required": [ "file" ], "properties": { "metadata": { "type": "object", "description": "JSON metadata part; see encoding at the path for contentType application/json.", "properties": { "file": { "type": "object", "properties": { "displayName": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "file": { "type": "string", "format": "binary" } }, "additionalProperties": false }, "encoding": { "metadata": { "contentType": "application/json" } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "name": { "type": "string", "description": "File resource name (e.g., files/abc123)" }, "displayName": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "string", "description": "Size in bytes (returned as string by Gemini API)" }, "createTime": { "type": "string", "format": "date-time" }, "updateTime": { "type": "string", "format": "date-time" }, "expirationTime": { "type": "string", "format": "date-time" }, "sha256Hash": { "type": "string" }, "uri": { "type": "string", "description": "URI for accessing the file content" }, "state": { "type": "string", "enum": [ "STATE_UNSPECIFIED", "PROCESSING", "ACTIVE", "FAILED" ] }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "videoMetadata": { "type": "object", "properties": { "videoDuration": { "type": "string" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/files": { "get": { "operationId": "geminiListFiles", "summary": "List files (Gemini format)", "description": "Lists uploaded files in Google Gemini API format.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "pageSize", "in": "query", "schema": { "type": "integer" }, "description": "Maximum number of files to return" }, { "name": "pageToken", "in": "query", "schema": { "type": "string" }, "description": "Page token for pagination" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "File resource name (e.g., files/abc123)" }, "displayName": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "string", "description": "Size in bytes (returned as string by Gemini API)" }, "createTime": { "type": "string", "format": "date-time" }, "updateTime": { "type": "string", "format": "date-time" }, "expirationTime": { "type": "string", "format": "date-time" }, "sha256Hash": { "type": "string" }, "uri": { "type": "string", "description": "URI for accessing the file content" }, "state": { "type": "string", "enum": [ "STATE_UNSPECIFIED", "PROCESSING", "ACTIVE", "FAILED" ] }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "videoMetadata": { "type": "object", "properties": { "videoDuration": { "type": "string" } } } } } }, "nextPageToken": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/files/{file_id}": { "get": { "operationId": "geminiRetrieveFile", "summary": "Retrieve file (Gemini format)", "description": "Retrieves file metadata in Google Gemini API format.\n\nNote: This endpoint returns file metadata only. Direct file content\ndownload is not supported by Gemini Files API. Use the file.uri\nfield from the response to access the file content.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "File resource name (e.g., files/abc123)" }, "displayName": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "string", "description": "Size in bytes (returned as string by Gemini API)" }, "createTime": { "type": "string", "format": "date-time" }, "updateTime": { "type": "string", "format": "date-time" }, "expirationTime": { "type": "string", "format": "date-time" }, "sha256Hash": { "type": "string" }, "uri": { "type": "string", "description": "URI for accessing the file content" }, "state": { "type": "string", "enum": [ "STATE_UNSPECIFIED", "PROCESSING", "ACTIVE", "FAILED" ] }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "videoMetadata": { "type": "object", "properties": { "videoDuration": { "type": "string" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "geminiDeleteFile", "summary": "Delete file (Gemini format)", "description": "Deletes a file in Google Gemini API format.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID to delete" } ], "responses": { "200": { "description": "Successful response (empty)", "content": { "application/json": { "schema": { "type": "object", "description": "Empty response on successful deletion" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/batches": { "get": { "operationId": "geminiListBatches", "summary": "List batch jobs (Gemini format)", "description": "Lists batch jobs in Gemini format. Supports `pageSize` / `pageToken` pagination.", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/batches/{batch_id}": { "get": { "operationId": "geminiRetrieveBatch", "summary": "Retrieve a batch job (Gemini format)", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "post": { "operationId": "geminiCancelBatch", "summary": "Cancel a batch job (Gemini format)", "description": "Cancels a batch job. Gemini conventionally sends the request as\n`/v1beta/batches/{batch_id}:cancel`; the router matches the `:cancel`\nsuffix into the `batch_id` path parameter.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch identifier, optionally with a `:cancel` action suffix." } ], "responses": { "200": { "description": "Cancellation accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "geminiDeleteBatch", "summary": "Delete a batch job (Gemini format)", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response (empty object on Gemini).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/cachedContents": { "post": { "operationId": "geminiCreateCachedContent", "summary": "Create cached content (Gemini format)", "description": "Creates a cached content entry that can be re-used across subsequent\ngenerate-content calls to reduce repeated prefix tokens.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override. Defaults to `gemini`. Use `vertex` to route to Vertex." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Gemini model identifier (e.g. `gemini-1.5-pro`). The `models/` prefix is stripped." }, "displayName": { "type": "string" }, "systemInstruction": { "type": "object", "description": "System instruction content.", "additionalProperties": true }, "contents": { "type": "array", "items": {} }, "tools": { "type": "array", "items": {} }, "toolConfig": {}, "ttl": { "type": "string", "description": "TTL in protobuf duration format (e.g. `3600s`)." }, "expireTime": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "geminiListCachedContents", "summary": "List cached content entries (Gemini format)", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/cachedContents/{cached_id}": { "get": { "operationId": "geminiRetrieveCachedContent", "summary": "Retrieve cached content (Gemini format)", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "cached_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Cached content not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "geminiUpdateCachedContent", "summary": "Update cached content (Gemini format)", "description": "Updates the TTL or expiration time of a cached content entry. Only\n`ttl` or `expireTime` may be modified.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "cached_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl": { "type": "string", "description": "TTL in protobuf duration format." }, "expireTime": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "geminiDeleteCachedContent", "summary": "Delete cached content (Gemini format)", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "cached_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deletion accepted. Returns an empty JSON object (`{}`), mirroring Gemini's native delete response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Cached content not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1/rank": { "post": { "operationId": "vertexRank", "summary": "Rerank documents (Vertex Rank)", "description": "Reranks records using Google Vertex AI's Ranking API. The request body\nfollows the Vertex `rankRecords` schema.\n", "tags": [ "GenAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Vertex ranking model identifier." }, "query": { "type": "string" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" } }, "additionalProperties": true } }, "topN": { "type": "integer" }, "ignoreRecordDetailsInResponse": { "type": "boolean" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/genai/v1beta/models/{model}/operations/{operation_id}": { "get": { "operationId": "geminiRetrieveVideoOperation", "summary": "Retrieve video generation operation (Gemini format)", "description": "Polls the status of a long-running video generation operation produced\nby `models/{model}:generateVideos`. The Gemini SDK appends the\noperation name as a wildcard path segment. If the operation name\ncontains `/`, it must be percent-encoded in the request path (for\nexample, `%2F`) to remain conformant with OpenAPI 3.x path-parameter\nsemantics.\n", "tags": [ "GenAI Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Video model identifier (e.g. `veo-3.1-generate-preview`)." }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Operation name. If it contains `/`, it must be percent-encoded in the request path (for example, `%2F`)." } ], "responses": { "200": { "description": "Operation status payload (Gemini video generation response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Operation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model/{modelId}/converse": { "post": { "operationId": "bedrockConverse", "summary": "Converse with model (Bedrock format)", "description": "Sends messages to a model using AWS Bedrock Converse API format.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID (e.g., anthropic.claude-3-sonnet-20240229-v1:0)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model/{modelId}/converse-stream": { "post": { "operationId": "bedrockConverseStream", "summary": "Stream converse with model (Bedrock format)", "description": "Streams messages from a model using AWS Bedrock Converse API format.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID (e.g., anthropic.claude-3-sonnet-20240229-v1:0)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "application/x-amz-eventstream": { "schema": { "type": "object", "description": "Flat structure for streaming events matching actual Bedrock API response", "properties": { "role": { "type": "string", "description": "For messageStart events" }, "contentBlockIndex": { "type": "integer", "description": "For content block events" }, "delta": { "type": "object", "properties": { "text": { "type": "string" }, "reasoningContent": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } } }, "toolUse": { "type": "object", "properties": { "input": { "type": "string" } } } } }, "stopReason": { "type": "string", "description": "For messageStop events" }, "start": { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" } } } } }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "cacheReadInputTokens": { "type": "integer" }, "cacheWriteInputTokens": { "type": "integer" } } }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "integer" } } }, "trace": { "type": "object" }, "additionalModelResponseFields": { "type": "object" }, "invokeModelRawChunk": { "type": "string", "format": "byte", "description": "Raw bytes for legacy invoke stream" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model/{modelId}/invoke": { "post": { "operationId": "bedrockInvokeModel", "summary": "Invoke model (Bedrock format)", "description": "Invokes a model using AWS Bedrock InvokeModel API format.\nAccepts raw model-specific request body.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID (e.g., anthropic.claude-3-sonnet-20240229-v1:0)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockInvokeRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockInvokeResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model/{modelId}/invoke-with-response-stream": { "post": { "operationId": "bedrockInvokeModelStream", "summary": "Invoke model with streaming (Bedrock format)", "description": "Invokes a model with streaming using AWS Bedrock InvokeModelWithResponseStream API format.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID (e.g., anthropic.claude-3-sonnet-20240229-v1:0)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockInvokeRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "application/x-amz-eventstream": { "schema": { "type": "object", "description": "AWS event stream format" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model/{modelId}/count-tokens": { "post": { "operationId": "bedrockCountTokens", "summary": "Count tokens (Bedrock format)", "description": "Counts tokens for a Converse-style request using AWS Bedrock format.\nThe request body must include `input.converse` with a complete Converse\npayload; only Converse-shaped input is supported.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bedrock model identifier (e.g. `anthropic.claude-3-5-sonnet-20240620-v1:0`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "object", "required": [ "converse" ], "properties": { "converse": { "description": "Converse-shaped request used to compute the token count.", "type": "object", "additionalProperties": true } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "inputTokens": { "type": "integer", "description": "Number of input tokens that would be billed for this request." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model-invocation-job": { "post": { "operationId": "bedrockCreateBatchJob", "summary": "Create batch inference job (Bedrock format)", "description": "Creates a batch inference job using AWS Bedrock format.\nRoutes to native Bedrock by default; set `x-model-provider` to route the\njob to another provider (`openai`, `gemini`, etc.).\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override for cross-provider batch routing." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockBatchJobRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockBatchJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model-invocation-jobs": { "get": { "operationId": "bedrockListBatchJobs", "summary": "List batch inference jobs (Bedrock format)", "description": "Lists batch inference jobs using AWS Bedrock format.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "maxResults", "in": "query", "schema": { "type": "integer" }, "description": "Maximum number of results to return" }, { "name": "nextToken", "in": "query", "schema": { "type": "string" }, "description": "Token for pagination" }, { "name": "statusEquals", "in": "query", "schema": { "type": "string", "enum": [ "Submitted", "InProgress", "Completed", "Failed", "Stopping", "Stopped", "PartiallyCompleted", "Expired", "Validating", "Scheduled" ] }, "description": "Filter by status" }, { "name": "nameContains", "in": "query", "schema": { "type": "string" }, "description": "Filter by job name containing this string" }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override for cross-provider batch routing." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "invocationJobSummaries": { "type": "array", "items": { "type": "object", "properties": { "jobArn": { "type": "string" }, "jobName": { "type": "string" }, "modelId": { "type": "string" }, "status": { "type": "string" }, "submitTime": { "type": "string", "format": "date-time" }, "lastModifiedTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "message": { "type": "string" } } } }, "nextToken": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model-invocation-job/{job_arn}": { "get": { "operationId": "bedrockRetrieveBatchJob", "summary": "Retrieve batch inference job (Bedrock format)", "description": "Retrieves a batch inference job using AWS Bedrock format.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "job_arn", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bedrock job ARN (URL-encoded). For non-Bedrock providers, the\n`arn:aws:bedrock:us-east-1:444444444444:batch:` prefix is stripped\nautomatically before routing.\n" }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override for cross-provider batch routing." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockBatchJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/model-invocation-job/{job_arn}/stop": { "post": { "operationId": "bedrockCancelBatchJob", "summary": "Cancel batch inference job (Bedrock format)", "description": "Stops a batch inference job using AWS Bedrock format.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "job_arn", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bedrock job ARN to stop (URL-encoded). For non-Bedrock providers, the\n`arn:aws:bedrock:us-east-1:444444444444:batch:` prefix is stripped\nautomatically before routing.\n" }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override for cross-provider batch routing." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobArn": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/files/{bucket}": { "get": { "operationId": "bedrockS3ListObjects", "summary": "S3-compatible ListObjectsV2", "description": "Lists objects in a bucket using S3 ListObjectsV2 semantics. Supports\nthe `prefix` and `max-keys` query parameters used by boto3.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bucket name." }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter keys by prefix." }, { "name": "max-keys", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of keys to return." }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override; defaults to `bedrock`." } ], "responses": { "200": { "description": "ListObjectsV2 result (S3 XML or JSON, depending on provider).", "content": { "application/xml": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal error returned as S3 XML.", "content": { "application/xml": { "schema": { "type": "string" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/bedrock/files/{bucket}/{key}": { "put": { "operationId": "bedrockS3PutObject", "summary": "S3-compatible PutObject", "description": "Uploads an object to the Bifrost file store using S3 PutObject semantics.\nThe response is empty with an `ETag` header, mirroring native S3.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bucket name." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object key. Supports `/`-separated nested keys (`{key:*}` wildcard)." }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override; defaults to `bedrock`." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw object bytes." } } } }, "responses": { "200": { "description": "Object stored. Empty body with `ETag` response header." }, "500": { "description": "Internal error returned as S3 XML.", "content": { "application/xml": { "schema": { "type": "string" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "bedrockS3GetObject", "summary": "S3-compatible GetObject", "description": "Retrieves raw object bytes from the Bifrost file store.", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bucket name." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object key (`{key:*}` wildcard)." }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override; defaults to `bedrock`." } ], "responses": { "200": { "description": "Raw object content.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Object not found (S3 XML error).", "content": { "application/xml": { "schema": { "type": "string" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "head": { "operationId": "bedrockS3HeadObject", "summary": "S3-compatible HeadObject", "description": "Returns S3 metadata headers (ETag, Content-Length, etc.) without a body.\n", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bucket name." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object key (`{key:*}` wildcard)." }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override; defaults to `bedrock`." } ], "responses": { "200": { "description": "Empty body with object metadata headers." }, "404": { "description": "Object not found (empty body)." } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "bedrockS3DeleteObject", "summary": "S3-compatible DeleteObject", "description": "Deletes an object from the Bifrost file store.", "tags": [ "Bedrock Integration" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bucket name." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object key (`{key:*}` wildcard)." }, { "name": "x-model-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional provider override; defaults to `bedrock`." } ], "responses": { "200": { "description": "Object deleted. Empty body." }, "500": { "description": "Internal error returned as S3 XML.", "content": { "application/xml": { "schema": { "type": "string" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cohere/v2/chat": { "post": { "operationId": "cohereChatV2", "summary": "Chat with model (Cohere v2 format)", "description": "Sends a chat request using Cohere v2 API format.\n", "tags": [ "Cohere Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message-start", "content-start", "content-delta", "content-end", "tool-plan-delta", "tool-call-start", "tool-call-delta", "tool-call-end", "citation-start", "citation-end", "message-end", "debug" ], "description": "Type of streaming event" }, "id": { "type": "string", "description": "Event ID (for message-start)" }, "index": { "type": "integer", "description": "Index for indexed events" }, "delta": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "description": "Message role (for message-start)" }, "content": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "thinking": { "type": "string" } } }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "thinking": { "type": "string" } } } } ], "description": "Content for content events" }, "tool_plan": { "type": "string", "description": "Tool plan content (for tool-plan-delta)" }, "tool_calls": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } ], "description": "Tool calls (for tool-call events)" }, "citations": { "oneOf": [ { "type": "object", "properties": { "start": { "type": "integer", "description": "Start position of cited text" }, "end": { "type": "integer", "description": "End position of cited text" }, "text": { "type": "string", "description": "Cited text" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "document" ], "description": "Source type" }, "id": { "type": "string", "description": "Source ID (nullable)" }, "tool_output": { "type": "object", "description": "Tool output (for tool sources)" }, "document": { "type": "object", "description": "Document data (for document sources)" } } } }, "content_index": { "type": "integer", "description": "Content index of the citation" }, "type": { "type": "string", "enum": [ "TEXT_CONTENT", "THINKING_CONTENT", "PLAN" ], "description": "Type of citation" } } }, { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "description": "Start position of cited text" }, "end": { "type": "integer", "description": "End position of cited text" }, "text": { "type": "string", "description": "Cited text" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "document" ], "description": "Source type" }, "id": { "type": "string", "description": "Source ID (nullable)" }, "tool_output": { "type": "object", "description": "Tool output (for tool sources)" }, "document": { "type": "object", "description": "Document data (for document sources)" } } } }, "content_index": { "type": "integer", "description": "Content index of the citation" }, "type": { "type": "string", "enum": [ "TEXT_CONTENT", "THINKING_CONTENT", "PLAN" ], "description": "Type of citation" } } } } ], "description": "Citations (for citation events)" } } }, "finish_reason": { "type": "string", "enum": [ "COMPLETE", "STOP_SEQUENCE", "MAX_TOKENS", "TOOL_CALL", "ERROR", "TIMEOUT" ] }, "usage": { "type": "object", "properties": { "billed_units": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of billed input tokens" }, "output_tokens": { "type": "integer", "description": "Number of billed output tokens" }, "search_units": { "type": "integer", "description": "Number of billed search units" }, "classifications": { "type": "integer", "description": "Number of billed classification units" } } }, "tokens": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens produced" } } }, "cached_tokens": { "type": "integer", "description": "Cached tokens" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cohere/v2/embed": { "post": { "operationId": "cohereEmbedV2", "summary": "Create embeddings (Cohere v2 format)", "description": "Creates embeddings using Cohere v2 API format.\n", "tags": [ "Cohere Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereEmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cohere/v2/rerank": { "post": { "operationId": "cohereRerank", "summary": "Rerank documents (Cohere format)", "description": "Reranks a list of documents against a query using Cohere's v2 Rerank\nAPI. The request body matches Cohere's native format.\n", "tags": [ "Cohere Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "query", "documents" ], "properties": { "model": { "type": "string", "description": "Cohere rerank model identifier (e.g. `rerank-english-v3.0`)." }, "query": { "type": "string", "description": "Query string to rank documents against." }, "documents": { "type": "array", "description": "Documents to rerank. Strings or objects with a `text` field.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } }, "additionalProperties": true } ] } }, "top_n": { "type": "integer", "description": "Return only the top N reranked results." }, "return_documents": { "type": "boolean", "description": "Include the original document text in the response." }, "max_tokens_per_doc": { "type": "integer", "description": "Truncate each document to this token limit before ranking." } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "relevance_score": { "type": "number" }, "document": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cohere/v1/tokenize": { "post": { "operationId": "cohereTokenize", "summary": "Tokenize text (Cohere format)", "description": "Tokenizes text using Cohere v1 API format.\n", "tags": [ "Cohere Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereCountTokensRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereCountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1/chat/completions": { "post": { "operationId": "cursorChatCompletions", "summary": "Cursor hybrid chat completions", "description": "Accepts Cursor's hybrid chat-completions payload (which is structurally\na Responses API request with `input` blocks) and returns a chat-\ncompletions-shaped response (`choices` + `delta` chunks for streams).\nRoutes the request through the Responses pipeline internally.\n", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming chat completion response (SSE format)", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "created": { "type": "integer" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1/models": { "get": { "operationId": "cursorListModels", "summary": "List models (Cursor)", "description": "Lists available models, returning the OpenAI `/v1/models` shape.", "tags": [ "Cursor Integration" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1/complete": { "post": { "operationId": "cursorAnthropicComplete", "summary": "Anthropic complete (Cursor mount)", "description": "Cursor mount of the legacy Anthropic `POST /v1/complete` endpoint.", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicTextRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "completion" }, "id": { "type": "string" }, "completion": { "type": "string" }, "stop_reason": { "type": "string", "enum": [ "stop_sequence", "max_tokens", null ] }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens generated" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1/messages": { "post": { "operationId": "cursorAnthropicMessages", "summary": "Anthropic messages (Cursor mount)", "description": "Cursor mount of `POST /anthropic/v1/messages`. Same request/response shape and streaming behaviour.", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message_start", "content_block_start", "content_block_delta", "content_block_stop", "message_delta", "message_stop", "ping", "error" ] }, "message": { "$ref": "#/components/schemas/AnthropicMessageResponse" }, "index": { "type": "integer" }, "content_block": { "$ref": "#/components/schemas/AnthropicContentBlock" }, "delta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_delta", "input_json_delta", "thinking_delta", "signature_delta" ] }, "text": { "type": "string" }, "partial_json": { "type": "string" }, "thinking": { "type": "string" }, "signature": { "type": "string" }, "stop_reason": { "type": "string" }, "stop_sequence": { "type": "string" } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" }, "cache_creation": { "type": "object", "properties": { "ephemeral_5m_input_tokens": { "type": "integer" }, "ephemeral_1h_input_tokens": { "type": "integer" } } } } }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1/messages/{path}": { "post": { "operationId": "cursorAnthropicMessagesWildcard", "summary": "Anthropic messages — wildcard (Cursor mount)", "description": "Cursor mount of the Anthropic messages wildcard (`POST /anthropic/v1/messages/{path}`).\nRoutes extended Anthropic messages endpoints (e.g. batches, count tokens)\nthrough Cursor.\n", "tags": [ "Cursor Integration" ], "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1/messages/count_tokens": { "post": { "operationId": "cursorAnthropicCountTokens", "summary": "Anthropic count tokens (Cursor mount)", "description": "Cursor mount of `POST /anthropic/v1/messages/count_tokens`.", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1beta/models": { "get": { "operationId": "cursorGeminiListModels", "summary": "Gemini list models (Cursor mount)", "description": "Cursor mount of `GET /genai/v1beta/models`.", "tags": [ "Cursor Integration" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1beta/models/{model}": { "post": { "operationId": "cursorGeminiModelAction", "summary": "Gemini model action (Cursor mount)", "description": "Cursor mount of Gemini's wildcard generate-content/embed/count-tokens/\npredict endpoints. The `model` path parameter includes the action\nsuffix (e.g. `gemini-pro:generateContent`).\n", "tags": [ "Cursor Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name optionally followed by an action suffix." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1beta/models/{model}/operations/{operation_id}": { "get": { "operationId": "cursorGeminiRetrieveVideoOperation", "summary": "Gemini video operation polling (Cursor mount)", "tags": [ "Cursor Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1/rank": { "post": { "operationId": "cursorVertexRank", "summary": "Vertex rank (Cursor mount)", "description": "Cursor mount of `POST /genai/v1/rank` — Vertex AI ranking.", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/model/{modelId}/converse": { "post": { "operationId": "cursorBedrockConverse", "summary": "Bedrock converse (Cursor mount)", "tags": [ "Cursor Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/model/{modelId}/converse-stream": { "post": { "operationId": "cursorBedrockConverseStream", "summary": "Bedrock converse stream (Cursor mount)", "tags": [ "Cursor Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "AWS event stream of converse chunks.", "content": { "application/vnd.amazon.eventstream": { "schema": { "type": "string", "format": "binary" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/model/{modelId}/invoke": { "post": { "operationId": "cursorBedrockInvoke", "summary": "Bedrock invoke (Cursor mount)", "tags": [ "Cursor Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Bedrock invoke response (raw model output).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/model/{modelId}/invoke-with-response-stream": { "post": { "operationId": "cursorBedrockInvokeStream", "summary": "Bedrock invoke-with-response-stream (Cursor mount)", "tags": [ "Cursor Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "AWS event stream of invoke chunks.", "content": { "application/vnd.amazon.eventstream": { "schema": { "type": "string", "format": "binary" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/rerank": { "post": { "operationId": "cursorBedrockRerank", "summary": "Bedrock rerank (Cursor mount)", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/model/{modelId}/count-tokens": { "post": { "operationId": "cursorBedrockCountTokens", "summary": "Bedrock count tokens (Cursor mount)", "tags": [ "Cursor Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object", "properties": { "converse": { "type": "object", "additionalProperties": true } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "inputTokens": { "type": "integer" } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v2/chat": { "post": { "operationId": "cursorCohereChat", "summary": "Cohere chat (Cursor mount)", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v2/embed": { "post": { "operationId": "cursorCohereEmbed", "summary": "Cohere embed (Cursor mount)", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v2/rerank": { "post": { "operationId": "cursorCohereRerank", "summary": "Cohere rerank (Cursor mount)", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/cursor/v1/tokenize": { "post": { "operationId": "cursorCohereTokenize", "summary": "Cohere tokenize (Cursor mount)", "tags": [ "Cursor Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/v1/completions": { "post": { "operationId": "litellmOpenAITextCompletions", "summary": "Text completions (LiteLLM - OpenAI format)", "description": "Creates a text completion using OpenAI-compatible format via LiteLLM.\nThis is the legacy completions API.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAITextCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming text completion response", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/v1/chat/completions": { "post": { "operationId": "litellmOpenAIChatCompletions", "summary": "Chat completions (LiteLLM - OpenAI format)", "description": "Creates a chat completion using OpenAI-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming chat completion response (SSE format)", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "created": { "type": "integer" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/v1/embeddings": { "post": { "operationId": "litellmOpenAIEmbeddings", "summary": "Create embeddings (LiteLLM - OpenAI format)", "description": "Creates embeddings using OpenAI-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/v1/models": { "get": { "operationId": "litellmOpenAIListModels", "summary": "List models (LiteLLM - OpenAI format)", "description": "Lists available models using OpenAI-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/v1/responses": { "post": { "operationId": "litellmOpenAIResponses", "summary": "Create response (LiteLLM - OpenAI Responses API)", "description": "Creates a response using OpenAI Responses API format via LiteLLM.\nSupports streaming via SSE.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming responses API response (SSE format)", "properties": { "type": { "type": "string", "enum": [ "response.ping", "response.created", "response.in_progress", "response.completed", "response.failed", "response.incomplete", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.refusal.delta", "response.refusal.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.results.added", "response.file_search_call.results.completed", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.web_search_call.results.added", "response.web_search_call.results.completed", "response.web_fetch_call.in_progress", "response.web_fetch_call.fetching", "response.web_fetch_call.completed", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.image_generation_call.completed", "response.image_generation_call.generating", "response.image_generation_call.in_progress", "response.image_generation_call.partial_image", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.mcp_call.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_list_tools.in_progress", "response.code_interpreter_call.in_progress", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.output_text.annotation.added", "response.output_text.annotation.done", "response.queued", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "error" ] }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "output_index": { "type": "integer" }, "item": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "content_index": { "type": "integer" }, "item_id": { "type": "string" }, "part": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "delta": { "type": "string" }, "signature": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "text": { "type": "string" }, "refusal": { "type": "string" }, "arguments": { "type": "string" }, "partial_image_b64": { "type": "string" }, "partial_image_index": { "type": "integer" }, "annotation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } }, "annotation_index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/v1/responses/input_tokens": { "post": { "operationId": "litellmOpenAICountInputTokens", "summary": "Count input tokens (LiteLLM - OpenAI format)", "description": "Counts the number of tokens in a Responses API request via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/v1/audio/speech": { "post": { "operationId": "litellmOpenAISpeech", "summary": "Create speech (LiteLLM - OpenAI TTS)", "description": "Generates audio from text using OpenAI TTS via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAISpeechRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "speech.audio.delta", "speech.audio.done" ] }, "audio": { "type": "string", "format": "byte" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/v1/audio/transcriptions": { "post": { "operationId": "litellmOpenAITranscriptions", "summary": "Create transcription (LiteLLM - OpenAI Whisper)", "description": "Transcribes audio into text using OpenAI Whisper via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OpenAITranscriptionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transcript.text.delta", "transcript.text.done" ] }, "delta": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" } } } } }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tokens", "duration" ] }, "input_tokens": { "type": "integer" }, "input_token_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "seconds": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/anthropic/v1/messages": { "post": { "operationId": "litellmAnthropicMessages", "summary": "Create message (LiteLLM - Anthropic format)", "description": "Creates a message using Anthropic-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message_start", "content_block_start", "content_block_delta", "content_block_stop", "message_delta", "message_stop", "ping", "error" ] }, "message": { "$ref": "#/components/schemas/AnthropicMessageResponse" }, "index": { "type": "integer" }, "content_block": { "$ref": "#/components/schemas/AnthropicContentBlock" }, "delta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_delta", "input_json_delta", "thinking_delta", "signature_delta" ] }, "text": { "type": "string" }, "partial_json": { "type": "string" }, "thinking": { "type": "string" }, "signature": { "type": "string" }, "stop_reason": { "type": "string" }, "stop_sequence": { "type": "string" } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" }, "cache_creation": { "type": "object", "properties": { "ephemeral_5m_input_tokens": { "type": "integer" }, "ephemeral_1h_input_tokens": { "type": "integer" } } } } }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/genai/v1beta/models": { "get": { "operationId": "litellmGeminiListModels", "summary": "List models (LiteLLM - Gemini format)", "description": "Lists available models in Google Gemini API format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "parameters": [ { "name": "pageSize", "in": "query", "schema": { "type": "integer" }, "description": "Maximum number of models to return" }, { "name": "pageToken", "in": "query", "schema": { "type": "string" }, "description": "Page token for pagination" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/genai/v1beta/models/{model}:generateContent": { "post": { "operationId": "litellmGeminiGenerateContent", "summary": "Generate content (LiteLLM - Gemini format)", "description": "Generates content using Google Gemini-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/genai/v1beta/models/{model}:streamGenerateContent": { "post": { "operationId": "litellmGeminiStreamGenerateContent", "summary": "Stream generate content (LiteLLM - Gemini format)", "description": "Streams content generation using Google Gemini-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/bedrock/model/{modelId}/converse": { "post": { "operationId": "litellmBedrockConverse", "summary": "Converse with model (LiteLLM - Bedrock format)", "description": "Sends messages using AWS Bedrock Converse-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/bedrock/model/{modelId}/converse-stream": { "post": { "operationId": "litellmBedrockConverseStream", "summary": "Stream converse with model (LiteLLM - Bedrock format)", "description": "Streams messages using AWS Bedrock Converse-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "application/x-amz-eventstream": { "schema": { "type": "object", "description": "Flat structure for streaming events matching actual Bedrock API response", "properties": { "role": { "type": "string", "description": "For messageStart events" }, "contentBlockIndex": { "type": "integer", "description": "For content block events" }, "delta": { "type": "object", "properties": { "text": { "type": "string" }, "reasoningContent": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } } }, "toolUse": { "type": "object", "properties": { "input": { "type": "string" } } } } }, "stopReason": { "type": "string", "description": "For messageStop events" }, "start": { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" } } } } }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "cacheReadInputTokens": { "type": "integer" }, "cacheWriteInputTokens": { "type": "integer" } } }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "integer" } } }, "trace": { "type": "object" }, "additionalModelResponseFields": { "type": "object" }, "invokeModelRawChunk": { "type": "string", "format": "byte", "description": "Raw bytes for legacy invoke stream" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/cohere/v2/chat": { "post": { "operationId": "litellmCohereChat", "summary": "Chat with model (LiteLLM - Cohere format)", "description": "Sends a chat request using Cohere-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message-start", "content-start", "content-delta", "content-end", "tool-plan-delta", "tool-call-start", "tool-call-delta", "tool-call-end", "citation-start", "citation-end", "message-end", "debug" ], "description": "Type of streaming event" }, "id": { "type": "string", "description": "Event ID (for message-start)" }, "index": { "type": "integer", "description": "Index for indexed events" }, "delta": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "description": "Message role (for message-start)" }, "content": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "thinking": { "type": "string" } } }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "thinking": { "type": "string" } } } } ], "description": "Content for content events" }, "tool_plan": { "type": "string", "description": "Tool plan content (for tool-plan-delta)" }, "tool_calls": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } ], "description": "Tool calls (for tool-call events)" }, "citations": { "oneOf": [ { "type": "object", "properties": { "start": { "type": "integer", "description": "Start position of cited text" }, "end": { "type": "integer", "description": "End position of cited text" }, "text": { "type": "string", "description": "Cited text" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "document" ], "description": "Source type" }, "id": { "type": "string", "description": "Source ID (nullable)" }, "tool_output": { "type": "object", "description": "Tool output (for tool sources)" }, "document": { "type": "object", "description": "Document data (for document sources)" } } } }, "content_index": { "type": "integer", "description": "Content index of the citation" }, "type": { "type": "string", "enum": [ "TEXT_CONTENT", "THINKING_CONTENT", "PLAN" ], "description": "Type of citation" } } }, { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "description": "Start position of cited text" }, "end": { "type": "integer", "description": "End position of cited text" }, "text": { "type": "string", "description": "Cited text" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "document" ], "description": "Source type" }, "id": { "type": "string", "description": "Source ID (nullable)" }, "tool_output": { "type": "object", "description": "Tool output (for tool sources)" }, "document": { "type": "object", "description": "Document data (for document sources)" } } } }, "content_index": { "type": "integer", "description": "Content index of the citation" }, "type": { "type": "string", "enum": [ "TEXT_CONTENT", "THINKING_CONTENT", "PLAN" ], "description": "Type of citation" } } } } ], "description": "Citations (for citation events)" } } }, "finish_reason": { "type": "string", "enum": [ "COMPLETE", "STOP_SEQUENCE", "MAX_TOKENS", "TOOL_CALL", "ERROR", "TIMEOUT" ] }, "usage": { "type": "object", "properties": { "billed_units": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of billed input tokens" }, "output_tokens": { "type": "integer", "description": "Number of billed output tokens" }, "search_units": { "type": "integer", "description": "Number of billed search units" }, "classifications": { "type": "integer", "description": "Number of billed classification units" } } }, "tokens": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens produced" } } }, "cached_tokens": { "type": "integer", "description": "Cached tokens" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/cohere/v2/embed": { "post": { "operationId": "litellmCohereEmbed", "summary": "Create embeddings (LiteLLM - Cohere format)", "description": "Creates embeddings using Cohere-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereEmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/litellm/cohere/v1/tokenize": { "post": { "operationId": "litellmCohereTokenize", "summary": "Tokenize text (LiteLLM - Cohere format)", "description": "Tokenizes text using Cohere-compatible format via LiteLLM.\n", "tags": [ "LiteLLM Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereCountTokensRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereCountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/v1/completions": { "post": { "operationId": "langchainOpenAITextCompletions", "summary": "Text completions (LangChain - OpenAI format)", "description": "Creates a text completion using OpenAI-compatible format via LangChain.\nThis is the legacy completions API.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAITextCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming text completion response", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/v1/chat/completions": { "post": { "operationId": "langchainOpenAIChatCompletions", "summary": "Chat completions (LangChain - OpenAI format)", "description": "Creates a chat completion using OpenAI-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming chat completion response (SSE format)", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "created": { "type": "integer" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/v1/embeddings": { "post": { "operationId": "langchainOpenAIEmbeddings", "summary": "Create embeddings (LangChain - OpenAI format)", "description": "Creates embeddings using OpenAI-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/v1/models": { "get": { "operationId": "langchainOpenAIListModels", "summary": "List models (LangChain - OpenAI format)", "description": "Lists available models using OpenAI-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/v1/responses": { "post": { "operationId": "langchainOpenAIResponses", "summary": "Create response (LangChain - OpenAI Responses API)", "description": "Creates a response using OpenAI Responses API format via LangChain.\nSupports streaming via SSE.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming responses API response (SSE format)", "properties": { "type": { "type": "string", "enum": [ "response.ping", "response.created", "response.in_progress", "response.completed", "response.failed", "response.incomplete", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.refusal.delta", "response.refusal.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.results.added", "response.file_search_call.results.completed", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.web_search_call.results.added", "response.web_search_call.results.completed", "response.web_fetch_call.in_progress", "response.web_fetch_call.fetching", "response.web_fetch_call.completed", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.image_generation_call.completed", "response.image_generation_call.generating", "response.image_generation_call.in_progress", "response.image_generation_call.partial_image", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.mcp_call.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_list_tools.in_progress", "response.code_interpreter_call.in_progress", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.output_text.annotation.added", "response.output_text.annotation.done", "response.queued", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "error" ] }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "output_index": { "type": "integer" }, "item": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "content_index": { "type": "integer" }, "item_id": { "type": "string" }, "part": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "delta": { "type": "string" }, "signature": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "text": { "type": "string" }, "refusal": { "type": "string" }, "arguments": { "type": "string" }, "partial_image_b64": { "type": "string" }, "partial_image_index": { "type": "integer" }, "annotation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } }, "annotation_index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/v1/responses/input_tokens": { "post": { "operationId": "langchainOpenAICountInputTokens", "summary": "Count input tokens (LangChain - OpenAI format)", "description": "Counts the number of tokens in a Responses API request via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/v1/audio/speech": { "post": { "operationId": "langchainOpenAISpeech", "summary": "Create speech (LangChain - OpenAI TTS)", "description": "Generates audio from text using OpenAI TTS via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAISpeechRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "speech.audio.delta", "speech.audio.done" ] }, "audio": { "type": "string", "format": "byte" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/v1/audio/transcriptions": { "post": { "operationId": "langchainOpenAITranscriptions", "summary": "Create transcription (LangChain - OpenAI Whisper)", "description": "Transcribes audio into text using OpenAI Whisper via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OpenAITranscriptionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transcript.text.delta", "transcript.text.done" ] }, "delta": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" } } } } }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tokens", "duration" ] }, "input_tokens": { "type": "integer" }, "input_token_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "seconds": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/anthropic/v1/messages": { "post": { "operationId": "langchainAnthropicMessages", "summary": "Create message (LangChain - Anthropic format)", "description": "Creates a message using Anthropic-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message_start", "content_block_start", "content_block_delta", "content_block_stop", "message_delta", "message_stop", "ping", "error" ] }, "message": { "$ref": "#/components/schemas/AnthropicMessageResponse" }, "index": { "type": "integer" }, "content_block": { "$ref": "#/components/schemas/AnthropicContentBlock" }, "delta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_delta", "input_json_delta", "thinking_delta", "signature_delta" ] }, "text": { "type": "string" }, "partial_json": { "type": "string" }, "thinking": { "type": "string" }, "signature": { "type": "string" }, "stop_reason": { "type": "string" }, "stop_sequence": { "type": "string" } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" }, "cache_creation": { "type": "object", "properties": { "ephemeral_5m_input_tokens": { "type": "integer" }, "ephemeral_1h_input_tokens": { "type": "integer" } } } } }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/anthropic/v1/messages/count_tokens": { "post": { "operationId": "langchainAnthropicCountTokens", "summary": "Count tokens (LangChain - Anthropic format)", "description": "Counts tokens using Anthropic-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AnthropicMessageRequest" } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/genai/v1beta/models": { "get": { "operationId": "langchainGeminiListModels", "summary": "List models (LangChain - Gemini format)", "description": "Lists available models in Google Gemini API format via LangChain.\n", "tags": [ "LangChain Integration" ], "parameters": [ { "name": "pageSize", "in": "query", "schema": { "type": "integer" }, "description": "Maximum number of models to return" }, { "name": "pageToken", "in": "query", "schema": { "type": "string" }, "description": "Page token for pagination" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/genai/v1beta/models/{model}:generateContent": { "post": { "operationId": "langchainGeminiGenerateContent", "summary": "Generate content (LangChain - Gemini format)", "description": "Generates content using Google Gemini-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/genai/v1beta/models/{model}:streamGenerateContent": { "post": { "operationId": "langchainGeminiStreamGenerateContent", "summary": "Stream generate content (LangChain - Gemini format)", "description": "Streams content generation using Google Gemini-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/bedrock/model/{modelId}/converse": { "post": { "operationId": "langchainBedrockConverse", "summary": "Converse with model (LangChain - Bedrock format)", "description": "Sends messages using AWS Bedrock Converse-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/bedrock/model/{modelId}/converse-stream": { "post": { "operationId": "langchainBedrockConverseStream", "summary": "Stream converse with model (LangChain - Bedrock format)", "description": "Streams messages using AWS Bedrock Converse-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "application/x-amz-eventstream": { "schema": { "type": "object", "description": "Flat structure for streaming events matching actual Bedrock API response", "properties": { "role": { "type": "string", "description": "For messageStart events" }, "contentBlockIndex": { "type": "integer", "description": "For content block events" }, "delta": { "type": "object", "properties": { "text": { "type": "string" }, "reasoningContent": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } } }, "toolUse": { "type": "object", "properties": { "input": { "type": "string" } } } } }, "stopReason": { "type": "string", "description": "For messageStop events" }, "start": { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" } } } } }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "cacheReadInputTokens": { "type": "integer" }, "cacheWriteInputTokens": { "type": "integer" } } }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "integer" } } }, "trace": { "type": "object" }, "additionalModelResponseFields": { "type": "object" }, "invokeModelRawChunk": { "type": "string", "format": "byte", "description": "Raw bytes for legacy invoke stream" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/cohere/v2/chat": { "post": { "operationId": "langchainCohereChat", "summary": "Chat with model (LangChain - Cohere format)", "description": "Sends a chat request using Cohere-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message-start", "content-start", "content-delta", "content-end", "tool-plan-delta", "tool-call-start", "tool-call-delta", "tool-call-end", "citation-start", "citation-end", "message-end", "debug" ], "description": "Type of streaming event" }, "id": { "type": "string", "description": "Event ID (for message-start)" }, "index": { "type": "integer", "description": "Index for indexed events" }, "delta": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "description": "Message role (for message-start)" }, "content": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "thinking": { "type": "string" } } }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "thinking": { "type": "string" } } } } ], "description": "Content for content events" }, "tool_plan": { "type": "string", "description": "Tool plan content (for tool-plan-delta)" }, "tool_calls": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } ], "description": "Tool calls (for tool-call events)" }, "citations": { "oneOf": [ { "type": "object", "properties": { "start": { "type": "integer", "description": "Start position of cited text" }, "end": { "type": "integer", "description": "End position of cited text" }, "text": { "type": "string", "description": "Cited text" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "document" ], "description": "Source type" }, "id": { "type": "string", "description": "Source ID (nullable)" }, "tool_output": { "type": "object", "description": "Tool output (for tool sources)" }, "document": { "type": "object", "description": "Document data (for document sources)" } } } }, "content_index": { "type": "integer", "description": "Content index of the citation" }, "type": { "type": "string", "enum": [ "TEXT_CONTENT", "THINKING_CONTENT", "PLAN" ], "description": "Type of citation" } } }, { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "description": "Start position of cited text" }, "end": { "type": "integer", "description": "End position of cited text" }, "text": { "type": "string", "description": "Cited text" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "document" ], "description": "Source type" }, "id": { "type": "string", "description": "Source ID (nullable)" }, "tool_output": { "type": "object", "description": "Tool output (for tool sources)" }, "document": { "type": "object", "description": "Document data (for document sources)" } } } }, "content_index": { "type": "integer", "description": "Content index of the citation" }, "type": { "type": "string", "enum": [ "TEXT_CONTENT", "THINKING_CONTENT", "PLAN" ], "description": "Type of citation" } } } } ], "description": "Citations (for citation events)" } } }, "finish_reason": { "type": "string", "enum": [ "COMPLETE", "STOP_SEQUENCE", "MAX_TOKENS", "TOOL_CALL", "ERROR", "TIMEOUT" ] }, "usage": { "type": "object", "properties": { "billed_units": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of billed input tokens" }, "output_tokens": { "type": "integer", "description": "Number of billed output tokens" }, "search_units": { "type": "integer", "description": "Number of billed search units" }, "classifications": { "type": "integer", "description": "Number of billed classification units" } } }, "tokens": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens produced" } } }, "cached_tokens": { "type": "integer", "description": "Cached tokens" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/cohere/v2/embed": { "post": { "operationId": "langchainCohereEmbed", "summary": "Create embeddings (LangChain - Cohere format)", "description": "Creates embeddings using Cohere-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereEmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/langchain/cohere/v1/tokenize": { "post": { "operationId": "langchainCohereTokenize", "summary": "Tokenize text (LangChain - Cohere format)", "description": "Tokenizes text using Cohere-compatible format via LangChain.\n", "tags": [ "LangChain Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereCountTokensRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereCountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/v1/completions": { "post": { "operationId": "pydanticaiOpenAITextCompletions", "summary": "Text completions (PydanticAI - OpenAI format)", "description": "Creates a text completion using OpenAI-compatible format via PydanticAI.\nThis is the legacy completions API.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAITextCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming text completion response", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/v1/chat/completions": { "post": { "operationId": "pydanticaiOpenAIChatCompletions", "summary": "Chat completions (PydanticAI - OpenAI format)", "description": "Creates a chat completion using OpenAI-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming chat completion response (SSE format)", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "created": { "type": "integer" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/v1/embeddings": { "post": { "operationId": "pydanticaiOpenAIEmbeddings", "summary": "Create embeddings (PydanticAI - OpenAI format)", "description": "Creates embeddings using OpenAI-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/v1/models": { "get": { "operationId": "pydanticaiOpenAIListModels", "summary": "List models (PydanticAI - OpenAI format)", "description": "Lists available models using OpenAI-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/v1/responses": { "post": { "operationId": "pydanticaiOpenAIResponses", "summary": "Create response (PydanticAI - OpenAI Responses API)", "description": "Creates a response using OpenAI Responses API format via PydanticAI.\nSupports streaming via SSE.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Streaming responses API response (SSE format)", "properties": { "type": { "type": "string", "enum": [ "response.ping", "response.created", "response.in_progress", "response.completed", "response.failed", "response.incomplete", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.refusal.delta", "response.refusal.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.results.added", "response.file_search_call.results.completed", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.web_search_call.results.added", "response.web_search_call.results.completed", "response.web_fetch_call.in_progress", "response.web_fetch_call.fetching", "response.web_fetch_call.completed", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.image_generation_call.completed", "response.image_generation_call.generating", "response.image_generation_call.in_progress", "response.image_generation_call.partial_image", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.mcp_call.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_list_tools.in_progress", "response.code_interpreter_call.in_progress", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.output_text.annotation.added", "response.output_text.annotation.done", "response.queued", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "error" ] }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "output_index": { "type": "integer" }, "item": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } }, "content_index": { "type": "integer" }, "item_id": { "type": "string" }, "part": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "delta": { "type": "string" }, "signature": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "text": { "type": "string" }, "refusal": { "type": "string" }, "arguments": { "type": "string" }, "partial_image_b64": { "type": "string" }, "partial_image_index": { "type": "integer" }, "annotation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } }, "annotation_index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/v1/responses/input_tokens": { "post": { "operationId": "pydanticaiOpenAICountInputTokens", "summary": "Count input tokens (PydanticAI - OpenAI format)", "description": "Counts the number of tokens in a Responses API request via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/v1/audio/speech": { "post": { "operationId": "pydanticaiOpenAISpeech", "summary": "Create speech (PydanticAI - OpenAI TTS)", "description": "Generates audio from text using OpenAI TTS via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAISpeechRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "speech.audio.delta", "speech.audio.done" ] }, "audio": { "type": "string", "format": "byte" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/v1/audio/transcriptions": { "post": { "operationId": "pydanticaiOpenAITranscriptions", "summary": "Create transcription (PydanticAI - OpenAI Whisper)", "description": "Transcribes audio into text using OpenAI Whisper via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OpenAITranscriptionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transcript.text.delta", "transcript.text.done" ] }, "delta": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" } } } } }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tokens", "duration" ] }, "input_tokens": { "type": "integer" }, "input_token_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "seconds": { "type": "integer" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/anthropic/v1/messages": { "post": { "operationId": "pydanticaiAnthropicMessages", "summary": "Create message (PydanticAI - Anthropic format)", "description": "Creates a message using Anthropic-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message_start", "content_block_start", "content_block_delta", "content_block_stop", "message_delta", "message_stop", "ping", "error" ] }, "message": { "$ref": "#/components/schemas/AnthropicMessageResponse" }, "index": { "type": "integer" }, "content_block": { "$ref": "#/components/schemas/AnthropicContentBlock" }, "delta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_delta", "input_json_delta", "thinking_delta", "signature_delta" ] }, "text": { "type": "string" }, "partial_json": { "type": "string" }, "thinking": { "type": "string" }, "signature": { "type": "string" }, "stop_reason": { "type": "string" }, "stop_sequence": { "type": "string" } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" }, "cache_creation": { "type": "object", "properties": { "ephemeral_5m_input_tokens": { "type": "integer" }, "ephemeral_1h_input_tokens": { "type": "integer" } } } } }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "default": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type (e.g., invalid_request_error, api_error)" }, "message": { "type": "string", "description": "Error message" } } } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/genai/v1beta/models": { "get": { "operationId": "pydanticaiGeminiListModels", "summary": "List models (PydanticAI - Gemini format)", "description": "Lists available models in Google Gemini API format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "parameters": [ { "name": "pageSize", "in": "query", "schema": { "type": "integer" }, "description": "Maximum number of models to return" }, { "name": "pageToken", "in": "query", "schema": { "type": "string" }, "description": "Page token for pagination" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiListModelsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/genai/v1beta/models/{model}:generateContent": { "post": { "operationId": "pydanticaiGeminiGenerateContent", "summary": "Generate content (PydanticAI - Gemini format)", "description": "Generates content using Google Gemini-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/genai/v1beta/models/{model}:streamGenerateContent": { "post": { "operationId": "pydanticaiGeminiStreamGenerateContent", "summary": "Stream generate content (PydanticAI - Gemini format)", "description": "Streams content generation using Google Gemini-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model name with action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerationRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/GeminiGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/bedrock/model/{modelId}/converse": { "post": { "operationId": "pydanticaiBedrockConverse", "summary": "Converse with model (PydanticAI - Bedrock format)", "description": "Sends messages using AWS Bedrock Converse-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/bedrock/model/{modelId}/converse-stream": { "post": { "operationId": "pydanticaiBedrockConverseStream", "summary": "Stream converse with model (PydanticAI - Bedrock format)", "description": "Streams messages using AWS Bedrock Converse-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockConverseRequest" } } } }, "responses": { "200": { "description": "Successful streaming response", "content": { "application/x-amz-eventstream": { "schema": { "type": "object", "description": "Flat structure for streaming events matching actual Bedrock API response", "properties": { "role": { "type": "string", "description": "For messageStart events" }, "contentBlockIndex": { "type": "integer", "description": "For content block events" }, "delta": { "type": "object", "properties": { "text": { "type": "string" }, "reasoningContent": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } } }, "toolUse": { "type": "object", "properties": { "input": { "type": "string" } } } } }, "stopReason": { "type": "string", "description": "For messageStop events" }, "start": { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" } } } } }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "cacheReadInputTokens": { "type": "integer" }, "cacheWriteInputTokens": { "type": "integer" } } }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "integer" } } }, "trace": { "type": "object" }, "additionalModelResponseFields": { "type": "object" }, "invokeModelRawChunk": { "type": "string", "format": "byte", "description": "Raw bytes for legacy invoke stream" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedrockError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/cohere/v2/chat": { "post": { "operationId": "pydanticaiCohereChat", "summary": "Chat with model (PydanticAI - Cohere format)", "description": "Sends a chat request using Cohere-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatResponse" } }, "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message-start", "content-start", "content-delta", "content-end", "tool-plan-delta", "tool-call-start", "tool-call-delta", "tool-call-end", "citation-start", "citation-end", "message-end", "debug" ], "description": "Type of streaming event" }, "id": { "type": "string", "description": "Event ID (for message-start)" }, "index": { "type": "integer", "description": "Index for indexed events" }, "delta": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "description": "Message role (for message-start)" }, "content": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "thinking": { "type": "string" } } }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "thinking": { "type": "string" } } } } ], "description": "Content for content events" }, "tool_plan": { "type": "string", "description": "Tool plan content (for tool-plan-delta)" }, "tool_calls": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } ], "description": "Tool calls (for tool-call events)" }, "citations": { "oneOf": [ { "type": "object", "properties": { "start": { "type": "integer", "description": "Start position of cited text" }, "end": { "type": "integer", "description": "End position of cited text" }, "text": { "type": "string", "description": "Cited text" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "document" ], "description": "Source type" }, "id": { "type": "string", "description": "Source ID (nullable)" }, "tool_output": { "type": "object", "description": "Tool output (for tool sources)" }, "document": { "type": "object", "description": "Document data (for document sources)" } } } }, "content_index": { "type": "integer", "description": "Content index of the citation" }, "type": { "type": "string", "enum": [ "TEXT_CONTENT", "THINKING_CONTENT", "PLAN" ], "description": "Type of citation" } } }, { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "description": "Start position of cited text" }, "end": { "type": "integer", "description": "End position of cited text" }, "text": { "type": "string", "description": "Cited text" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "document" ], "description": "Source type" }, "id": { "type": "string", "description": "Source ID (nullable)" }, "tool_output": { "type": "object", "description": "Tool output (for tool sources)" }, "document": { "type": "object", "description": "Document data (for document sources)" } } } }, "content_index": { "type": "integer", "description": "Content index of the citation" }, "type": { "type": "string", "enum": [ "TEXT_CONTENT", "THINKING_CONTENT", "PLAN" ], "description": "Type of citation" } } } } ], "description": "Citations (for citation events)" } } }, "finish_reason": { "type": "string", "enum": [ "COMPLETE", "STOP_SEQUENCE", "MAX_TOKENS", "TOOL_CALL", "ERROR", "TIMEOUT" ] }, "usage": { "type": "object", "properties": { "billed_units": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of billed input tokens" }, "output_tokens": { "type": "integer", "description": "Number of billed output tokens" }, "search_units": { "type": "integer", "description": "Number of billed search units" }, "classifications": { "type": "integer", "description": "Number of billed classification units" } } }, "tokens": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens produced" } } }, "cached_tokens": { "type": "integer", "description": "Cached tokens" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/cohere/v2/embed": { "post": { "operationId": "pydanticaiCohereEmbed", "summary": "Create embeddings (PydanticAI - Cohere format)", "description": "Creates embeddings using Cohere-compatible format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereEmbeddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereEmbeddingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/pydanticai/cohere/v1/tokenize": { "post": { "operationId": "pydanticaiCohereTokenize", "summary": "Tokenize text (PydanticAI - Cohere format)", "description": "Tokenizes text using Cohere v1 API format via PydanticAI.\n", "tags": [ "PydanticAI Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereCountTokensRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereCountTokensResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/health": { "get": { "operationId": "getHealth", "summary": "Health check", "description": "Returns the health status of the Bifrost server. Checks connectivity to config store,\nlog store, and vector store if configured.\n", "tags": [ "Health" ], "responses": { "200": { "description": "Server is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/config": { "get": { "operationId": "getConfig", "summary": "Get configuration", "description": "Retrieves the current Bifrost configuration including client config, framework config,\nauth config, and connection status for various stores.\n", "tags": [ "Configuration" ], "parameters": [ { "name": "from_db", "in": "query", "description": "If true, fetch configuration directly from the database", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConfigResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateConfig", "summary": "Update configuration", "description": "Updates the Bifrost configuration. Supports hot-reloading of certain settings\nlike drop_excess_requests. Some settings may require a restart to take effect.\n", "tags": [ "Configuration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConfigRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Configuration updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/version": { "get": { "operationId": "getVersion", "summary": "Get version", "description": "Returns the current Bifrost version information.", "tags": [ "Configuration" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } } }, "/api/proxy-config": { "get": { "operationId": "getProxyConfig", "summary": "Get proxy configuration", "description": "Retrieves the current global proxy configuration.", "tags": [ "Configuration" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Global proxy configuration", "properties": { "enabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "http", "socks5", "tcp" ] }, "url": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string", "description": "Password (redacted as in responses)" }, "no_proxy": { "type": "string" }, "timeout": { "type": "integer" }, "skip_tls_verify": { "type": "boolean" }, "enable_for_scim": { "type": "boolean" }, "enable_for_inference": { "type": "boolean" }, "enable_for_api": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateProxyConfig", "summary": "Update proxy configuration", "description": "Updates the global proxy configuration.", "tags": [ "Configuration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Global proxy configuration", "properties": { "enabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "http", "socks5", "tcp" ] }, "url": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string", "description": "Password (redacted as in responses)" }, "no_proxy": { "type": "string" }, "timeout": { "type": "integer" }, "skip_tls_verify": { "type": "boolean" }, "enable_for_scim": { "type": "boolean" }, "enable_for_inference": { "type": "boolean" }, "enable_for_api": { "type": "boolean" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Proxy configuration updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/pricing/force-sync": { "post": { "operationId": "forceSyncPricing", "summary": "Force pricing sync", "description": "Triggers an immediate pricing sync and resets the pricing sync timer.", "tags": [ "Configuration" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Pricing sync triggered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users": { "get": { "operationId": "listUsers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List users", "description": "Returns a paginated list of users with optional search.", "tags": [ "Users" ], "parameters": [ { "name": "offset", "in": "query", "description": "Zero-based result offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Number of users per page (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "search", "in": "query", "description": "Search by name or email", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "users", "count", "total_count", "limit", "offset" ], "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "count": { "type": "integer", "description": "Number of users in this response" }, "total_count": { "type": "integer", "description": "Total number of users matching the query" }, "limit": { "type": "integer", "description": "Requested page size, or the returned collection size when unpaged" }, "offset": { "type": "integer", "description": "Zero-based result offset" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createUser", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create user", "description": "Manually creates a new user in the organization.", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$", "description": "User's email address (must be unique)" }, "role_id": { "type": "integer", "description": "Optional RBAC role ID to assign" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "User created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "User with this email already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}": { "get": { "operationId": "getUser", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get user", "description": "Returns a single Enterprise user.", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteUser", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete user", "description": "Permanently removes a user from the organization. This cascades to delete the user's governance settings (budget/rate limits), team memberships, access profiles, and OIDC sessions. Cannot delete yourself.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request (e.g. cannot delete yourself)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/me/permissions": { "get": { "operationId": "getCurrentUserPermissions", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get current user permissions", "description": "Returns the RBAC permissions for the authenticated user. When SCIM is not enabled, returns full permissions for all resources. Otherwise returns the permissions associated with the user's assigned role.\n", "tags": [ "Users" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "object", "description": "Map of resource names to their permitted operations. When SCIM is disabled, returns full permissions for all resources.\n", "additionalProperties": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized (user not authenticated)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/role": { "put": { "operationId": "assignUserRole", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Assign role to user", "description": "Assigns an RBAC role to a user. This also auto-assigns the default access profile for the new role and reloads the RBAC permission cache.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "integer", "description": "ID of the RBAC role to assign" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role assigned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User or role not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/teams": { "get": { "operationId": "getUserTeams", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get user's teams", "description": "Returns the list of teams a user belongs to, including the membership source.", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "source": { "type": "string", "description": "How the user was added to this team (e.g. \"manual\", \"scim_sync\")" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateUserTeams", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update user's team assignments", "description": "Replaces the user's manual team assignments. Synced team memberships (from SCIM providers) are preserved and cannot be removed via this endpoint.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "team_ids" ], "properties": { "team_ids": { "type": "array", "items": { "type": "string" }, "description": "List of team IDs to assign (replaces existing manual assignments; synced memberships are preserved)" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Teams updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request (e.g. team not found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/governance": { "post": { "operationId": "createUserGovernance", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create user governance", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "User-scoped governance settings. POST creates settings and PUT partially updates them.", "properties": { "user_id": { "type": "string", "description": "Optional body copy of the path user ID. When present, it must match the path." }, "budget": { "$ref": "#/components/schemas/CreateBudgetRequest" }, "budgets": { "type": "array", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/CreateRateLimitRequest" }, "provider_configs": { "type": "array", "description": "Optional Enterprise per-provider governance overrides.", "items": { "type": "object", "additionalProperties": true } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Governance created", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "User governance already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateUserGovernance", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update user governance", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "User-scoped governance settings. POST creates settings and PUT partially updates them.", "properties": { "user_id": { "type": "string", "description": "Optional body copy of the path user ID. When present, it must match the path." }, "budget": { "$ref": "#/components/schemas/CreateBudgetRequest" }, "budgets": { "type": "array", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/CreateRateLimitRequest" }, "provider_configs": { "type": "array", "description": "Optional Enterprise per-provider governance overrides.", "items": { "type": "object", "additionalProperties": true } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Governance updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteUserGovernance", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete user governance", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Governance deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/virtual-keys": { "get": { "operationId": "listUserVirtualKeys", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List virtual keys available to a user", "tags": [ "Users", "Virtual Keys" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "User virtual keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "virtual_keys": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } }, "/api/governance/users/email/{email}/virtual-keys": { "get": { "operationId": "getUserVirtualKeysByEmail", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get user's virtual keys by email", "description": "**Enterprise only.**\nReturns all virtual keys associated with a user, looked up by email address. Returns an empty `virtual_keys` array when the user exists but has no virtual keys assigned. Intended for MDM and credential-helper integrations that need to resolve a user's keys without knowing their internal ID.\n", "tags": [ "Users" ], "parameters": [ { "name": "email", "in": "path", "required": true, "description": "URL-encoded email address of the user", "schema": { "type": "string", "format": "email" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Internal ID of the resolved user" }, "email": { "type": "string", "format": "email", "description": "Email address of the resolved user" }, "virtual_keys": { "type": "array", "description": "Virtual keys assigned to this user", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Virtual key ID" }, "name": { "type": "string", "description": "Virtual key display name" }, "value": { "type": "string", "description": "Virtual key token value" }, "is_active": { "type": "boolean", "nullable": true, "description": "Whether the virtual key is currently active" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/email/{email}": { "get": { "operationId": "getUserByEmail", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get user by email", "description": "Returns a single Enterprise user resolved by URL-encoded email address.", "tags": [ "Users" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/teams/{team_id}/members": { "get": { "operationId": "getTeamMembers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List team members", "description": "Returns all members of a team with their user details and membership source.", "tags": [ "Teams" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "user_name": { "type": "string" }, "user_email": { "type": "string" }, "source": { "type": "string", "description": "How the member was added (e.g. \"manual\", \"scim_sync\")" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "addTeamMember", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Add team member", "description": "Adds a user to a team. Both the team and user must exist.", "tags": [ "Teams" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "ID of the user to add to the team" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Member added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Team or user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "409": { "description": "User is already a member of this team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/teams/{team_id}/members/{user_id}": { "delete": { "operationId": "removeTeamMember", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Remove team member", "description": "Removes a user from a team.", "tags": [ "Teams" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "description": "User ID to remove", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Member removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Membership not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/session/login": { "post": { "operationId": "login", "summary": "Login", "description": "Authenticates a user and returns a session token.\nSets a cookie with the session token for subsequent requests.\n", "tags": [ "Session" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "security": [], "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "403": { "description": "Authentication is not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/session/logout": { "post": { "operationId": "logout", "summary": "Logout", "description": "Logs out the current user and invalidates the session token.", "tags": [ "Session" ], "security": [ { "ManagementBearerAuth": [] }, { "SessionCookieAuth": [] } ], "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "type": "object", "description": "Logout response", "properties": { "message": { "type": "string", "example": "Logout successful" } } } } } }, "403": { "description": "Authentication is not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/session/is-auth-enabled": { "get": { "operationId": "isAuthEnabled", "summary": "Check if authentication is enabled", "description": "Returns whether authentication is enabled and if the current token is valid.", "tags": [ "Session" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsAuthEnabledResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/session/ws-ticket": { "post": { "operationId": "issueWSTicket", "summary": "Issue WebSocket ticket", "description": "Issues a short-lived ticket for authenticating WebSocket connections.\nThe ticket can be used as a query parameter when upgrading to WebSocket.\n", "tags": [ "Session" ], "security": [ { "ManagementBearerAuth": [] }, { "SessionCookieAuth": [] } ], "responses": { "200": { "description": "Ticket issued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "string", "description": "Short-lived WebSocket authentication ticket" } } } } } }, "403": { "description": "Authentication is not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/providers": { "get": { "operationId": "listProviders", "summary": "List all providers", "description": "Returns a list of all configured providers with their configurations and status.", "tags": [ "Providers" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProvidersResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "addProvider", "summary": "Add a new provider", "description": "Adds a new provider with the specified configuration.", "tags": [ "Providers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProviderRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Provider added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "Provider already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/providers/{provider}": { "get": { "operationId": "getProvider", "summary": "Get a specific provider", "description": "Returns the configuration for a specific provider.", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Provider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateProvider", "summary": "Update a provider", "description": "Updates a provider's configuration. Expects ALL fields to be provided,\nincluding both edited and non-edited fields. Partial updates are not supported.\n", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Provider updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteProvider", "summary": "Delete a provider", "description": "Removes a provider from the configuration.", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Provider deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Provider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/providers/{provider}/keys": { "get": { "operationId": "listProviderKeys", "summary": "List keys for a provider", "description": "Returns all keys configured for a specific provider.", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProviderKeysResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Provider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createProviderKey", "summary": "Create a key for a provider", "description": "Creates a new API key for the specified provider. The key `id` is auto-generated\nif omitted. `enabled` defaults to `true` if omitted. `value` is required and must\nnot be empty. Keys cannot be created on keyless providers.\n", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Key created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Provider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "Key ID already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/providers/{provider}/keys/{key_id}": { "get": { "operationId": "getProviderKey", "summary": "Get a specific key for a provider", "description": "Returns a single key for the specified provider.", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } }, { "name": "key_id", "in": "path", "required": true, "description": "Key ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Provider or key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateProviderKey", "summary": "Update a key for a provider", "description": "Updates an existing key. Send the full key object. Redacted values sent back\nunchanged are automatically preserved (the server merges them with the stored\nraw values).\n", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } }, { "name": "key_id", "in": "path", "required": true, "description": "Key ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Key updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Provider or key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteProviderKey", "summary": "Delete a key from a provider", "description": "Deletes a key from the specified provider. Returns the deleted key.", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } }, { "name": "key_id", "in": "path", "required": true, "description": "Key ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Key deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Provider or key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/keys": { "get": { "operationId": "listKeys", "summary": "List all keys", "description": "Returns a list of all configured API keys across all providers.", "tags": [ "Providers" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/models": { "get": { "operationId": "listModelsManagement", "summary": "List models", "description": "Lists available models with optional filtering by query, provider, or keys.\n", "tags": [ "Providers" ], "parameters": [ { "name": "query", "in": "query", "description": "Filter models by name (case-insensitive partial match)", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "Filter by specific provider name", "schema": { "type": "string" } }, { "name": "keys", "in": "query", "description": "Comma-separated list of key IDs to filter models accessible by those keys", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (default 5)", "schema": { "type": "integer", "default": 5 } }, { "name": "unfiltered", "in": "query", "description": "If true, return all models including those filtered out by provider-level restrictions", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "List models response", "properties": { "models": { "type": "array", "items": { "type": "object", "description": "Model information", "properties": { "name": { "type": "string" }, "provider": { "type": "string" }, "accessible_by_keys": { "type": "array", "items": { "type": "string" } } } } }, "total": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/models/details": { "get": { "operationId": "listModelDetailsManagement", "summary": "List model details", "description": "Lists available models with capability metadata, when available from the model catalog, with optional filtering by query, provider, or keys.\n", "tags": [ "Providers" ], "parameters": [ { "name": "query", "in": "query", "description": "Filter models by name (case-insensitive partial match)", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "Filter by specific provider name", "schema": { "type": "string" } }, { "name": "keys", "in": "query", "description": "Comma-separated list of key IDs to filter models accessible by those keys", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (default 20)", "schema": { "type": "integer", "default": 20 } }, { "name": "unfiltered", "in": "query", "description": "If true, return all models including those filtered out by provider-level restrictions", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "List model details response", "properties": { "models": { "type": "array", "items": { "type": "object", "description": "Model details with capability metadata", "properties": { "name": { "type": "string" }, "provider": { "type": "string" }, "context_length": { "type": "integer" }, "max_input_tokens": { "type": "integer" }, "max_output_tokens": { "type": "integer" }, "input_cost_per_token": { "type": "number", "format": "double" }, "output_cost_per_token": { "type": "number", "format": "double" }, "cache_creation_input_token_cost": { "type": "number", "format": "double" }, "cache_read_input_token_cost": { "type": "number", "format": "double" }, "architecture": { "type": "object", "properties": { "modality": { "type": "string" }, "tokenizer": { "type": "string" }, "instruct_type": { "type": "string" }, "input_modalities": { "type": "array", "items": { "type": "string" } }, "output_modalities": { "type": "array", "items": { "type": "string" } } } }, "additional_attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "accessible_by_keys": { "type": "array", "items": { "type": "string" } } } } }, "total": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/models/parameters": { "get": { "operationId": "getModelParameters", "summary": "Get model parameters", "description": "Returns the available parameter definitions for a model. The model ID is resolved against the model-parameters catalog with fallbacks, so provider-qualified IDs returned by /v1/models (e.g. \"openai/gpt-4o\", \"openrouter/openai/gpt-4o\") and bare aliases of provider-qualified catalog entries resolve to the same record as the stored key.", "tags": [ "Providers" ], "security": [ { "ManagementBearerAuth": [] } ], "parameters": [ { "name": "model", "in": "query", "required": true, "description": "Model ID to get parameters for; provider-qualified IDs are resolved automatically", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/models/base": { "get": { "operationId": "listBaseModels", "summary": "List base models", "description": "Returns a list of base models from the model catalog.", "tags": [ "Providers" ], "parameters": [ { "name": "query", "in": "query", "description": "Filter models by name", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "Filter by provider", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/plugins": { "get": { "operationId": "listPlugins", "summary": "List all plugins", "description": "Returns a list of all plugins with their configurations and status.\nThe `actualName` field contains the plugin name from `GetName()` (used as the map key),\nwhile `name` contains the display name from the configuration.\nThe `types` array in the status shows which interfaces the plugin implements (llm, mcp, http).\n", "tags": [ "Plugins" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPluginsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createPlugin", "summary": "Create a new plugin", "description": "Creates a new plugin with the specified configuration.\nSetting `path` on a non-builtin plugin loads native code (a .so, via dlopen) into the\ngateway process and requires genuine admin authentication - it is refused with 403 if\ndashboard authentication is disabled or unconfigured, even though other management\nendpoints remain reachable in that state. Only `http`/`https` URLs are fetched for\nremote paths, and by default only ones resolving to a public address; private,\nloopback, link-local, and CGNAT addresses are additionally allowed if explicitly\nlisted in the deploy-time `server.plugin_download_private_allowlist` config. Local\nfilesystem paths are unaffected.\n", "tags": [ "Plugins" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePluginRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Plugin created successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Plugin operation response", "properties": { "message": { "type": "string" }, "plugin": { "$ref": "#/components/schemas/Plugin" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "403": { "description": "A non-builtin path was supplied and dashboard authentication is disabled or unconfigured (the request was not genuinely authenticated)" }, "409": { "description": "Plugin already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/plugins/builtins": { "get": { "operationId": "listBuiltinPlugins", "summary": "List built-in plugin names", "description": "Returns the canonical list of built-in plugin names available in this Bifrost build.\nUse this to discover which plugins can be enabled without supplying a custom binary.\n", "tags": [ "Plugins" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Built-in plugin names retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "plugins": { "type": "array", "description": "Canonical names of built-in plugins", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/plugins/{name}": { "get": { "operationId": "getPlugin", "summary": "Get a specific plugin", "description": "Returns the configuration for a specific plugin.\nThe response includes the plugin status with types array showing which interfaces\nthe plugin implements (llm, mcp, http). The `actualName` field shows the plugin name\nfrom GetName() (used as the map key), which may differ from the display name (`name`).\n", "tags": [ "Plugins" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Plugin display name (the config field `name`, not the internal `actualName` from GetName())", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plugin" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Plugin not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updatePlugin", "summary": "Update a plugin", "description": "Updates a plugin's configuration. Will reload or stop the plugin based on enabled status.\nThe response `actualName` field shows the plugin name from GetName() (used as the map key),\nwhich may differ from the display name (`name`).\nSetting `path` on a non-builtin plugin loads native code (a .so, via dlopen) into the\ngateway process and requires genuine admin authentication - it is refused with 403 if\ndashboard authentication is disabled or unconfigured, even though other management\nendpoints remain reachable in that state. Only `http`/`https` URLs are fetched for\nremote paths, and by default only ones resolving to a public address; private,\nloopback, link-local, and CGNAT addresses are additionally allowed if explicitly\nlisted in the deploy-time `server.plugin_download_private_allowlist` config. Local\nfilesystem paths are unaffected.\n", "tags": [ "Plugins" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Plugin display name (the config field `name`, not the internal `actualName` from GetName())", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePluginRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Plugin updated successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Plugin operation response", "properties": { "message": { "type": "string" }, "plugin": { "$ref": "#/components/schemas/Plugin" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "403": { "description": "A non-builtin path was supplied and dashboard authentication is disabled or unconfigured (the request was not genuinely authenticated)" }, "404": { "description": "Plugin not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deletePlugin", "summary": "Delete a plugin", "description": "Removes a plugin from the configuration and stops it if running.", "tags": [ "Plugins" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Plugin display name (the config field `name`, not the internal `actualName` from GetName())", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Plugin deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Plugin not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/v1/mcp/tool/execute": { "post": { "operationId": "executeMCPTool", "summary": "Execute MCP tool", "description": "Executes an MCP tool and returns the result.", "tags": [ "MCP" ], "parameters": [ { "name": "format", "in": "query", "required": false, "description": "Format of the tool execution request/response.\n", "schema": { "type": "string", "enum": [ "chat", "responses" ], "default": "chat" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteToolRequest" }, "examples": { "chat": { "summary": "Chat format example", "value": { "id": "call_123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"location\": \"San Francisco\"}" } } }, "responses": { "summary": "Responses format example", "value": { "call_id": "call_123", "name": "get_weather", "arguments": "{\"location\": \"San Francisco\"}" } } } } } }, "responses": { "200": { "description": "Tool executed successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ChatMessage", "title": "Chat (Default)", "description": "Chat format response" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } }, "title": "Responses", "description": "Responses format response" } ], "description": "MCP tool execution response.\n" }, "examples": { "chat": { "summary": "Chat format response", "value": { "name": "get_weather", "role": "tool", "tool_call_id": "call_123", "content": "The weather in San Francisco is 72°F and sunny." } }, "responses": { "summary": "Responses format response", "value": { "id": "msg_123", "type": "function_call_output", "status": "completed", "role": "assistant", "call_id": "call_123", "name": "get_weather", "arguments": "{\"location\": \"San Francisco\"}", "content": "The weather in San Francisco is 72°F and sunny." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/mcp/clients": { "get": { "operationId": "getMCPClients", "summary": "List MCP clients", "description": "Returns a paginated list of configured MCP clients with their tools and connection state.\nSupports case-insensitive name search and exact-match filtering by connection type, auth type,\ncode-mode, and enabled/disabled status. Multi-value filters accept a comma-separated list and\nuse OR semantics within a field.\n", "tags": [ "MCP" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of clients to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "description": "Number of clients to skip.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "search", "in": "query", "description": "Case-insensitive search by client name.", "schema": { "type": "string" } }, { "name": "server", "in": "query", "description": "Filter to a single client by its exact client_id.", "schema": { "type": "string" } }, { "name": "connection_type", "in": "query", "description": "Comma-separated connection types to include (OR semantics).", "schema": { "type": "string", "example": "http,sse" } }, { "name": "auth_type", "in": "query", "description": "Comma-separated auth types to include (OR semantics).", "schema": { "type": "string", "example": "oauth,per_user_oauth" } }, { "name": "state", "in": "query", "description": "Comma-separated runtime connection states to include (OR semantics),\nresolved against live engine state. Only `healthy` and\n`unstable` are meaningful filter values: `healthy` matches\nclients the engine currently reports as healthy; `unstable`\nmatches everything else (error, pending states, needs_reauth,\ndisabled, not present in the engine). Selecting both, or neither,\napplies no state filter. Note the response-only needs_reauth\nprojection on per-user clients happens after filtering, so such\nclients still match `healthy`.\n", "schema": { "type": "string", "example": "healthy" } }, { "name": "all_virtual_keys", "in": "query", "description": "When true, include clients that are open to all virtual keys (allow_on_all_virtual_keys). ORs with virtual_keys.", "schema": { "type": "boolean" } }, { "name": "virtual_keys", "in": "query", "description": "Comma-separated virtual key IDs; includes clients explicitly assigned to any of them. ORs with all_virtual_keys.", "schema": { "type": "string" } }, { "name": "code_mode", "in": "query", "description": "Filter by code-mode clients. Omit for no filter.", "schema": { "type": "boolean" } }, { "name": "disabled", "in": "query", "description": "Filter by disabled status — true returns disabled clients, false returns enabled clients. Omit for no filter.", "schema": { "type": "boolean" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated list of MCP clients.", "required": [ "clients", "count", "total_count", "limit", "offset" ], "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/MCPClient" } }, "count": { "type": "integer", "description": "Number of clients returned in this page" }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of clients matching the query (before pagination)" }, "limit": { "type": "integer", "description": "Page size used for the response" }, "offset": { "type": "integer", "description": "Page offset used for the response" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client": { "post": { "operationId": "addMCPClient", "summary": "Add MCP client", "description": "Adds a new MCP client with the specified configuration.\nNote: tool_pricing is not available when creating a new client; tool\npricing can only be set once the tool list is known. For shared-connection\nclients tools are fetched after client creation; for per-user auth types\nthey are discovered during the create/verify flow itself.\n", "tags": [ "MCP" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "type": "object", "required": [ "name", "connection_type" ], "allOf": [ { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "const": "per_user_headers" } } }, "then": { "required": [ "per_user_header_keys" ], "properties": { "per_user_header_keys": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } }, "description": "When `auth_type` is `per_user_headers`, `per_user_header_keys` must\ndeclare at least one header name — the submission flow has nothing\nto ask the end-user for otherwise.\n" } }, { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "const": "token_exchange" } } }, "then": { "required": [ "token_exchange" ], "description": "When `auth_type` is `token_exchange`, `token_exchange` must declare\nat least `audience`, plus either `client_id` or\n`use_idp_credentials: true` — there is nothing to scope the\nexchange to, or exchange with, otherwise.\n" } }, { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "not": { "const": "token_exchange" } } } }, "then": { "not": { "required": [ "token_exchange" ] }, "description": "A `token_exchange` block only applies to auth_type \"token_exchange\";\nreject it for every other auth_type instead of silently ignoring it.\n" } } ], "properties": { "client_id": { "type": "string", "description": "Unique identifier for the MCP client (optional, auto-generated if not provided)" }, "name": { "type": "string", "description": "Display name for the MCP client" }, "is_code_mode_client": { "type": "boolean" }, "is_ping_available": { "type": "boolean", "default": true, "description": "Whether the MCP server supports ping for health checks.\nIf true, uses lightweight ping method for health checks.\nIf false, uses listTools method for health checks instead.\n" }, "needs_session_stickiness": { "type": "boolean", "default": false, "description": "HTTP-only. Only meaningful for auth_type \"oauth\", \"headers\", or \"none\"\n(a server-level connection) — per-user auth types are always per-call\nregardless of this field. When true, Bifrost holds one persistent\nupstream connection, reused for every tool call. When false or\nomitted (the default), a fresh connection is dialed per tool call.\nCannot be set to false for connection_type \"sse\" or \"stdio\" — both\nare always sticky.\n" }, "tool_sync_interval": { "type": "integer", "minimum": 0, "description": "Per-client tool-list sync interval in minutes. 0 (or omitted) falls back\nto the global mcp_tool_sync_interval client config.\n" }, "tool_execution_timeout": { "type": "integer", "minimum": 0, "description": "Per-client tool execution timeout in seconds. 0 (or omitted) falls back\nto the global mcp_tool_execution_timeout client config.\n" }, "allowed_extra_headers": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of request-level headers callers may forward to this MCP\nserver at execution time.\n[\"*\"] => any header may be forwarded\n[] or omitted => no extra headers are forwarded\n[\"header1\", \"header2\"] => only the specified headers\n" }, "connection_type": { "type": "string", "enum": [ "http", "stdio", "sse", "inprocess" ], "description": "Connection type for MCP client" }, "auth_type": { "type": "string", "enum": [ "none", "headers", "oauth", "per_user_oauth", "per_user_headers", "token_exchange" ], "description": "Authentication type for the MCP connection" }, "oauth_config_id": { "type": "string", "description": "OAuth config ID for OAuth authentication.\nSet after OAuth flow is completed. References the oauth_configs table.\nOnly relevant when auth_type is \"oauth\".\n" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests.\nOnly used when auth_type is \"headers\".\n" }, "oauth_config": { "$ref": "#/components/schemas/OAuthConfigRequest", "description": "OAuth configuration for initiating OAuth flow.\nRequired when creating a client with auth_type \"oauth\" or \"per_user_oauth\".\nThis will trigger the OAuth flow and return an authorization URL\n(see the pending_oauth response variant).\n" }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "Include-only list for tools.\n[\"*\"] => all tools are included\n[] => no tools are included\n[\"tool1\", \"tool2\"] => include only the specified tools\n" }, "tools_to_auto_execute": { "type": "array", "items": { "type": "string" }, "description": "List of tools that can be auto-executed without user approval.\nMust be a subset of tools_to_execute.\n[\"*\"] => all executable tools can be auto-executed\n[] => no tools are auto-executed\n[\"tool1\", \"tool2\"] => only specified tools can be auto-executed\n" }, "allow_on_all_virtual_keys": { "type": "boolean", "default": false, "description": "When true, this MCP client's tools are available to all virtual keys by default,\nwithout requiring an explicit virtual key assignment.\nAn explicit virtual key config always overrides this setting for that key.\n" }, "tls_config": { "type": "object", "description": "TLS configuration for HTTP and SSE connections.\nNot applicable to stdio or inprocess connection types.\n", "properties": { "insecure_skip_verify": { "type": "boolean", "description": "Disable TLS certificate verification. Takes priority over ca_cert_pem when both are set.\nUse only in development or trusted isolated environments. Not recommended for production.\n" }, "ca_cert_pem": { "type": "string", "description": "PEM-encoded CA certificate to trust for MCP server connections.\nUse when the MCP server uses a self-signed or private CA certificate.\nSupports env.VAR_NAME syntax to read the certificate from an environment variable.\n" } } }, "per_user_header_keys": { "type": "array", "items": { "type": "string" }, "description": "Required when `auth_type` is `per_user_headers`. List of header names each\nend-user must supply the first time they hit this MCP server. Values are\nsubmitted per user via the inline-401 flow — never persisted on the MCP\nclient config.\n" }, "token_exchange": { "type": "object", "required": [ "audience" ], "properties": { "audience": { "type": "string", "minLength": 1, "description": "Resource identifier this server is scoped to at the identity provider (e.g. \"api://jira-mcp\")" }, "use_idp_credentials": { "type": "boolean", "description": "When true, performs the exchange as the SSO login application itself\ninstead of client_id/client_secret below, which are then ignored.\nSome providers require this: Microsoft Entra ID's on-behalf-of grant\nonly accepts an assertion audienced to the exchanging application,\nand the SSO login flow always requests a token self-audienced to the\nSSO application, so a separate exchange application can never\nreceive a usable one.\n" }, "client_id": { "type": "string", "minLength": 1, "description": "The identity-provider application authorized to perform exchanges for\nthis audience — typically a dedicated registration carrying the\ntoken-exchange (or on-behalf-of) grant, separate from the SSO login\napplication. Required unless use_idp_credentials is true. Supports\nenv.VAR_NAME and vault.path references. Redacted in API responses.\n" }, "client_secret": { "type": "string", "description": "Secret for the exchange application; omit for public clients. Ignored\nwhen use_idp_credentials is true. Supports env.VAR_NAME and\nvault.path references. Redacted in API responses.\n" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes to request on the exchanged token. Include\n\"offline_access\" (where the identity provider supports it) so the\nretained admin discovery credential gets a refresh token and stays\nself-renewing.\n" }, "authorization_server_url": { "type": "string", "description": "Overrides the Authorization Server the exchange request is sent to.\nOnly needed when the audience is registered on a different\nAuthorization Server than the one used for SSO login (e.g. Okta's\nper-resource Custom Authorization Servers). Leave unset to use the\ndeployment's SSO login issuer, which is correct for providers with a\nsingle tenant-wide token endpoint (Entra, Auth0).\n" } }, "allOf": [ { "if": { "not": { "properties": { "use_idp_credentials": { "const": true } }, "required": [ "use_idp_credentials" ] } }, "then": { "required": [ "client_id" ], "description": "client_id is required unless use_idp_credentials is true, in which\ncase the exchange uses the SSO login application's own credentials\ninstead.\n" } } ], "additionalProperties": false, "description": "Required when creating a client with auth_type \"token_exchange\".\nVerification runs automatically as the signed-in admin (see\nPOST /api/mcp/client/{id}/verify-exchange) — there is no sample-token\nfield on this request.\n" }, "user_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Used only at create time when `auth_type` is `per_user_headers`. A sample\nset of header values the admin supplies so Bifrost can run a one-time\nupstream verify and discover the tool list. Not persisted by the create\ncall; each end-user submits their own values at runtime. To have Bifrost\nretain an admin discovery credential for periodic tool-list refresh,\nuse POST /api/mcp/client/{id}/verify-headers, which stores the sample\nvalues as that credential.\n" } } }, { "type": "object", "required": [ "connection_string" ], "properties": { "connection_type": { "type": "string", "enum": [ "http" ] }, "connection_string": { "type": "string", "description": "HTTP URL (required for HTTP connection type)" } } } ] }, { "allOf": [ { "type": "object", "required": [ "name", "connection_type" ], "allOf": [ { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "const": "per_user_headers" } } }, "then": { "required": [ "per_user_header_keys" ], "properties": { "per_user_header_keys": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } }, "description": "When `auth_type` is `per_user_headers`, `per_user_header_keys` must\ndeclare at least one header name — the submission flow has nothing\nto ask the end-user for otherwise.\n" } }, { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "const": "token_exchange" } } }, "then": { "required": [ "token_exchange" ], "description": "When `auth_type` is `token_exchange`, `token_exchange` must declare\nat least `audience`, plus either `client_id` or\n`use_idp_credentials: true` — there is nothing to scope the\nexchange to, or exchange with, otherwise.\n" } }, { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "not": { "const": "token_exchange" } } } }, "then": { "not": { "required": [ "token_exchange" ] }, "description": "A `token_exchange` block only applies to auth_type \"token_exchange\";\nreject it for every other auth_type instead of silently ignoring it.\n" } } ], "properties": { "client_id": { "type": "string", "description": "Unique identifier for the MCP client (optional, auto-generated if not provided)" }, "name": { "type": "string", "description": "Display name for the MCP client" }, "is_code_mode_client": { "type": "boolean" }, "is_ping_available": { "type": "boolean", "default": true, "description": "Whether the MCP server supports ping for health checks.\nIf true, uses lightweight ping method for health checks.\nIf false, uses listTools method for health checks instead.\n" }, "needs_session_stickiness": { "type": "boolean", "default": false, "description": "HTTP-only. Only meaningful for auth_type \"oauth\", \"headers\", or \"none\"\n(a server-level connection) — per-user auth types are always per-call\nregardless of this field. When true, Bifrost holds one persistent\nupstream connection, reused for every tool call. When false or\nomitted (the default), a fresh connection is dialed per tool call.\nCannot be set to false for connection_type \"sse\" or \"stdio\" — both\nare always sticky.\n" }, "tool_sync_interval": { "type": "integer", "minimum": 0, "description": "Per-client tool-list sync interval in minutes. 0 (or omitted) falls back\nto the global mcp_tool_sync_interval client config.\n" }, "tool_execution_timeout": { "type": "integer", "minimum": 0, "description": "Per-client tool execution timeout in seconds. 0 (or omitted) falls back\nto the global mcp_tool_execution_timeout client config.\n" }, "allowed_extra_headers": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of request-level headers callers may forward to this MCP\nserver at execution time.\n[\"*\"] => any header may be forwarded\n[] or omitted => no extra headers are forwarded\n[\"header1\", \"header2\"] => only the specified headers\n" }, "connection_type": { "type": "string", "enum": [ "http", "stdio", "sse", "inprocess" ], "description": "Connection type for MCP client" }, "auth_type": { "type": "string", "enum": [ "none", "headers", "oauth", "per_user_oauth", "per_user_headers", "token_exchange" ], "description": "Authentication type for the MCP connection" }, "oauth_config_id": { "type": "string", "description": "OAuth config ID for OAuth authentication.\nSet after OAuth flow is completed. References the oauth_configs table.\nOnly relevant when auth_type is \"oauth\".\n" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests.\nOnly used when auth_type is \"headers\".\n" }, "oauth_config": { "$ref": "#/components/schemas/OAuthConfigRequest", "description": "OAuth configuration for initiating OAuth flow.\nRequired when creating a client with auth_type \"oauth\" or \"per_user_oauth\".\nThis will trigger the OAuth flow and return an authorization URL\n(see the pending_oauth response variant).\n" }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "Include-only list for tools.\n[\"*\"] => all tools are included\n[] => no tools are included\n[\"tool1\", \"tool2\"] => include only the specified tools\n" }, "tools_to_auto_execute": { "type": "array", "items": { "type": "string" }, "description": "List of tools that can be auto-executed without user approval.\nMust be a subset of tools_to_execute.\n[\"*\"] => all executable tools can be auto-executed\n[] => no tools are auto-executed\n[\"tool1\", \"tool2\"] => only specified tools can be auto-executed\n" }, "allow_on_all_virtual_keys": { "type": "boolean", "default": false, "description": "When true, this MCP client's tools are available to all virtual keys by default,\nwithout requiring an explicit virtual key assignment.\nAn explicit virtual key config always overrides this setting for that key.\n" }, "tls_config": { "type": "object", "description": "TLS configuration for HTTP and SSE connections.\nNot applicable to stdio or inprocess connection types.\n", "properties": { "insecure_skip_verify": { "type": "boolean", "description": "Disable TLS certificate verification. Takes priority over ca_cert_pem when both are set.\nUse only in development or trusted isolated environments. Not recommended for production.\n" }, "ca_cert_pem": { "type": "string", "description": "PEM-encoded CA certificate to trust for MCP server connections.\nUse when the MCP server uses a self-signed or private CA certificate.\nSupports env.VAR_NAME syntax to read the certificate from an environment variable.\n" } } }, "per_user_header_keys": { "type": "array", "items": { "type": "string" }, "description": "Required when `auth_type` is `per_user_headers`. List of header names each\nend-user must supply the first time they hit this MCP server. Values are\nsubmitted per user via the inline-401 flow — never persisted on the MCP\nclient config.\n" }, "token_exchange": { "type": "object", "required": [ "audience" ], "properties": { "audience": { "type": "string", "minLength": 1, "description": "Resource identifier this server is scoped to at the identity provider (e.g. \"api://jira-mcp\")" }, "use_idp_credentials": { "type": "boolean", "description": "When true, performs the exchange as the SSO login application itself\ninstead of client_id/client_secret below, which are then ignored.\nSome providers require this: Microsoft Entra ID's on-behalf-of grant\nonly accepts an assertion audienced to the exchanging application,\nand the SSO login flow always requests a token self-audienced to the\nSSO application, so a separate exchange application can never\nreceive a usable one.\n" }, "client_id": { "type": "string", "minLength": 1, "description": "The identity-provider application authorized to perform exchanges for\nthis audience — typically a dedicated registration carrying the\ntoken-exchange (or on-behalf-of) grant, separate from the SSO login\napplication. Required unless use_idp_credentials is true. Supports\nenv.VAR_NAME and vault.path references. Redacted in API responses.\n" }, "client_secret": { "type": "string", "description": "Secret for the exchange application; omit for public clients. Ignored\nwhen use_idp_credentials is true. Supports env.VAR_NAME and\nvault.path references. Redacted in API responses.\n" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes to request on the exchanged token. Include\n\"offline_access\" (where the identity provider supports it) so the\nretained admin discovery credential gets a refresh token and stays\nself-renewing.\n" }, "authorization_server_url": { "type": "string", "description": "Overrides the Authorization Server the exchange request is sent to.\nOnly needed when the audience is registered on a different\nAuthorization Server than the one used for SSO login (e.g. Okta's\nper-resource Custom Authorization Servers). Leave unset to use the\ndeployment's SSO login issuer, which is correct for providers with a\nsingle tenant-wide token endpoint (Entra, Auth0).\n" } }, "allOf": [ { "if": { "not": { "properties": { "use_idp_credentials": { "const": true } }, "required": [ "use_idp_credentials" ] } }, "then": { "required": [ "client_id" ], "description": "client_id is required unless use_idp_credentials is true, in which\ncase the exchange uses the SSO login application's own credentials\ninstead.\n" } } ], "additionalProperties": false, "description": "Required when creating a client with auth_type \"token_exchange\".\nVerification runs automatically as the signed-in admin (see\nPOST /api/mcp/client/{id}/verify-exchange) — there is no sample-token\nfield on this request.\n" }, "user_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Used only at create time when `auth_type` is `per_user_headers`. A sample\nset of header values the admin supplies so Bifrost can run a one-time\nupstream verify and discover the tool list. Not persisted by the create\ncall; each end-user submits their own values at runtime. To have Bifrost\nretain an admin discovery credential for periodic tool-list refresh,\nuse POST /api/mcp/client/{id}/verify-headers, which stores the sample\nvalues as that credential.\n" } } }, { "type": "object", "required": [ "connection_string" ], "properties": { "connection_type": { "type": "string", "enum": [ "sse" ] }, "connection_string": { "type": "string", "description": "SSE URL (required for SSE connection type)" } } } ] }, { "allOf": [ { "type": "object", "required": [ "name", "connection_type" ], "allOf": [ { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "const": "per_user_headers" } } }, "then": { "required": [ "per_user_header_keys" ], "properties": { "per_user_header_keys": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } }, "description": "When `auth_type` is `per_user_headers`, `per_user_header_keys` must\ndeclare at least one header name — the submission flow has nothing\nto ask the end-user for otherwise.\n" } }, { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "const": "token_exchange" } } }, "then": { "required": [ "token_exchange" ], "description": "When `auth_type` is `token_exchange`, `token_exchange` must declare\nat least `audience`, plus either `client_id` or\n`use_idp_credentials: true` — there is nothing to scope the\nexchange to, or exchange with, otherwise.\n" } }, { "if": { "required": [ "auth_type" ], "properties": { "auth_type": { "not": { "const": "token_exchange" } } } }, "then": { "not": { "required": [ "token_exchange" ] }, "description": "A `token_exchange` block only applies to auth_type \"token_exchange\";\nreject it for every other auth_type instead of silently ignoring it.\n" } } ], "properties": { "client_id": { "type": "string", "description": "Unique identifier for the MCP client (optional, auto-generated if not provided)" }, "name": { "type": "string", "description": "Display name for the MCP client" }, "is_code_mode_client": { "type": "boolean" }, "is_ping_available": { "type": "boolean", "default": true, "description": "Whether the MCP server supports ping for health checks.\nIf true, uses lightweight ping method for health checks.\nIf false, uses listTools method for health checks instead.\n" }, "needs_session_stickiness": { "type": "boolean", "default": false, "description": "HTTP-only. Only meaningful for auth_type \"oauth\", \"headers\", or \"none\"\n(a server-level connection) — per-user auth types are always per-call\nregardless of this field. When true, Bifrost holds one persistent\nupstream connection, reused for every tool call. When false or\nomitted (the default), a fresh connection is dialed per tool call.\nCannot be set to false for connection_type \"sse\" or \"stdio\" — both\nare always sticky.\n" }, "tool_sync_interval": { "type": "integer", "minimum": 0, "description": "Per-client tool-list sync interval in minutes. 0 (or omitted) falls back\nto the global mcp_tool_sync_interval client config.\n" }, "tool_execution_timeout": { "type": "integer", "minimum": 0, "description": "Per-client tool execution timeout in seconds. 0 (or omitted) falls back\nto the global mcp_tool_execution_timeout client config.\n" }, "allowed_extra_headers": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of request-level headers callers may forward to this MCP\nserver at execution time.\n[\"*\"] => any header may be forwarded\n[] or omitted => no extra headers are forwarded\n[\"header1\", \"header2\"] => only the specified headers\n" }, "connection_type": { "type": "string", "enum": [ "http", "stdio", "sse", "inprocess" ], "description": "Connection type for MCP client" }, "auth_type": { "type": "string", "enum": [ "none", "headers", "oauth", "per_user_oauth", "per_user_headers", "token_exchange" ], "description": "Authentication type for the MCP connection" }, "oauth_config_id": { "type": "string", "description": "OAuth config ID for OAuth authentication.\nSet after OAuth flow is completed. References the oauth_configs table.\nOnly relevant when auth_type is \"oauth\".\n" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests.\nOnly used when auth_type is \"headers\".\n" }, "oauth_config": { "$ref": "#/components/schemas/OAuthConfigRequest", "description": "OAuth configuration for initiating OAuth flow.\nRequired when creating a client with auth_type \"oauth\" or \"per_user_oauth\".\nThis will trigger the OAuth flow and return an authorization URL\n(see the pending_oauth response variant).\n" }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "Include-only list for tools.\n[\"*\"] => all tools are included\n[] => no tools are included\n[\"tool1\", \"tool2\"] => include only the specified tools\n" }, "tools_to_auto_execute": { "type": "array", "items": { "type": "string" }, "description": "List of tools that can be auto-executed without user approval.\nMust be a subset of tools_to_execute.\n[\"*\"] => all executable tools can be auto-executed\n[] => no tools are auto-executed\n[\"tool1\", \"tool2\"] => only specified tools can be auto-executed\n" }, "allow_on_all_virtual_keys": { "type": "boolean", "default": false, "description": "When true, this MCP client's tools are available to all virtual keys by default,\nwithout requiring an explicit virtual key assignment.\nAn explicit virtual key config always overrides this setting for that key.\n" }, "tls_config": { "type": "object", "description": "TLS configuration for HTTP and SSE connections.\nNot applicable to stdio or inprocess connection types.\n", "properties": { "insecure_skip_verify": { "type": "boolean", "description": "Disable TLS certificate verification. Takes priority over ca_cert_pem when both are set.\nUse only in development or trusted isolated environments. Not recommended for production.\n" }, "ca_cert_pem": { "type": "string", "description": "PEM-encoded CA certificate to trust for MCP server connections.\nUse when the MCP server uses a self-signed or private CA certificate.\nSupports env.VAR_NAME syntax to read the certificate from an environment variable.\n" } } }, "per_user_header_keys": { "type": "array", "items": { "type": "string" }, "description": "Required when `auth_type` is `per_user_headers`. List of header names each\nend-user must supply the first time they hit this MCP server. Values are\nsubmitted per user via the inline-401 flow — never persisted on the MCP\nclient config.\n" }, "token_exchange": { "type": "object", "required": [ "audience" ], "properties": { "audience": { "type": "string", "minLength": 1, "description": "Resource identifier this server is scoped to at the identity provider (e.g. \"api://jira-mcp\")" }, "use_idp_credentials": { "type": "boolean", "description": "When true, performs the exchange as the SSO login application itself\ninstead of client_id/client_secret below, which are then ignored.\nSome providers require this: Microsoft Entra ID's on-behalf-of grant\nonly accepts an assertion audienced to the exchanging application,\nand the SSO login flow always requests a token self-audienced to the\nSSO application, so a separate exchange application can never\nreceive a usable one.\n" }, "client_id": { "type": "string", "minLength": 1, "description": "The identity-provider application authorized to perform exchanges for\nthis audience — typically a dedicated registration carrying the\ntoken-exchange (or on-behalf-of) grant, separate from the SSO login\napplication. Required unless use_idp_credentials is true. Supports\nenv.VAR_NAME and vault.path references. Redacted in API responses.\n" }, "client_secret": { "type": "string", "description": "Secret for the exchange application; omit for public clients. Ignored\nwhen use_idp_credentials is true. Supports env.VAR_NAME and\nvault.path references. Redacted in API responses.\n" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes to request on the exchanged token. Include\n\"offline_access\" (where the identity provider supports it) so the\nretained admin discovery credential gets a refresh token and stays\nself-renewing.\n" }, "authorization_server_url": { "type": "string", "description": "Overrides the Authorization Server the exchange request is sent to.\nOnly needed when the audience is registered on a different\nAuthorization Server than the one used for SSO login (e.g. Okta's\nper-resource Custom Authorization Servers). Leave unset to use the\ndeployment's SSO login issuer, which is correct for providers with a\nsingle tenant-wide token endpoint (Entra, Auth0).\n" } }, "allOf": [ { "if": { "not": { "properties": { "use_idp_credentials": { "const": true } }, "required": [ "use_idp_credentials" ] } }, "then": { "required": [ "client_id" ], "description": "client_id is required unless use_idp_credentials is true, in which\ncase the exchange uses the SSO login application's own credentials\ninstead.\n" } } ], "additionalProperties": false, "description": "Required when creating a client with auth_type \"token_exchange\".\nVerification runs automatically as the signed-in admin (see\nPOST /api/mcp/client/{id}/verify-exchange) — there is no sample-token\nfield on this request.\n" }, "user_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Used only at create time when `auth_type` is `per_user_headers`. A sample\nset of header values the admin supplies so Bifrost can run a one-time\nupstream verify and discover the tool list. Not persisted by the create\ncall; each end-user submits their own values at runtime. To have Bifrost\nretain an admin discovery credential for periodic tool-list refresh,\nuse POST /api/mcp/client/{id}/verify-headers, which stores the sample\nvalues as that credential.\n" } } }, { "type": "object", "required": [ "stdio_config" ], "properties": { "connection_type": { "type": "string", "enum": [ "stdio" ] }, "stdio_config": { "type": "object", "description": "STDIO configuration (required for STDIO connection type)", "properties": { "command": { "type": "string", "description": "Executable command to run" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Command line arguments" }, "envs": { "type": "array", "items": { "type": "string" }, "description": "Environment variables required" } } } } } ] } ], "discriminator": { "propertyName": "connection_type", "mapping": { "http": "#/MCPClientCreateRequestHTTP", "sse": "#/MCPClientCreateRequestSSE", "stdio": "#/MCPClientCreateRequestSTDIO" } }, "description": "MCP client configuration for creating a new client (tool_pricing not available at creation).\nThe schema varies based on connection_type:\n- HTTP/SSE: connection_string is required\n- STDIO: stdio_config is required\n- InProcess: server instance must be provided programmatically (Go package only)\n" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP client added successfully. For auth_type \"oauth\" and\n\"per_user_oauth\" the client is not created yet — the response is the\npending_oauth variant carrying authorize_url plus status_url /\ncomplete_url / next_steps hints; the client is created when the flow\nis completed via complete_url.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "$ref": "#/components/schemas/OAuthFlowInitiation" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client/{id}": { "put": { "operationId": "editMCPClient", "summary": "Edit MCP client", "description": "Updates an existing MCP client's configuration. All fields are optional\n(PATCH semantics); connection_type, auth_type, connection_string,\nstdio_config, and oauth_config_id are immutable after creation.\nUnlike client creation, tool_pricing can be included to set per-tool execution costs since tools are already fetched.\nFor OAuth-based clients, providing oauth_config rotates the stored OAuth\nconfiguration in place and flips every bound token to needs_reauth when\na field actually changes (see MCPClientUpdateRequest.oauth_config).\nOptionally provide vk_configs to manage which virtual keys have access to this MCP server and with which tools. When provided, this fully replaces all existing VK assignments in a single atomic transaction.\nSet disabled: true to shut down the client's connection and workers without removing it. Set disabled: false to reconnect a previously disabled client.\n", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP client ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "MCP client configuration for updating an existing client (includes tool_pricing).\nAll fields are optional; omitting a field retains its existing value (PATCH\nsemantics). Immutable fields (connection_type, auth_type, connection_string,\nstdio_config, oauth_config_id) are not accepted here; they cannot be changed\nafter creation.\n", "properties": { "name": { "type": "string", "description": "Display name for the MCP client" }, "is_code_mode_client": { "type": "boolean", "description": "Whether this client is available in code mode" }, "is_ping_available": { "type": "boolean", "description": "Whether the MCP server supports ping for health checks.\nIf true, uses lightweight ping method for health checks.\nIf false, uses listTools method for health checks instead.\n" }, "needs_session_stickiness": { "type": "boolean", "description": "HTTP-only. Only meaningful for auth_type \"oauth\", \"headers\", or \"none\"\n— per-user auth types are always per-call regardless of this field.\nWhen true, Bifrost holds one persistent upstream connection, reused\nfor every tool call. When false, a fresh connection is dialed per\ntool call. Cannot be set to false for connection_type \"sse\" or\n\"stdio\" — both are always sticky.\n" }, "tool_sync_interval": { "type": "integer", "minimum": 0, "description": "Per-client tool-list sync interval in minutes. 0 falls back to the\nglobal mcp_tool_sync_interval client config.\n" }, "tool_execution_timeout": { "type": "integer", "minimum": 0, "description": "Per-client tool execution timeout in seconds. 0 falls back to the\nglobal mcp_tool_execution_timeout client config.\n" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests.\nOnly used when auth_type is \"headers\". Supports env./vault. references.\nValues echoed back redacted from a GET response are recognized and\npreserve the stored value, so a fetch-modify-put round trip is safe.\n" }, "allowed_extra_headers": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of request-level headers callers may forward to this MCP\nserver at execution time.\n[\"*\"] => any header may be forwarded\n[] => no extra headers are forwarded\n[\"header1\", \"header2\"] => only the specified headers\n" }, "oauth_config": { "$ref": "#/components/schemas/OAuthConfigRequest", "description": "Rotates the stored OAuth configuration in place. Only accepted for\nauth_type \"oauth\" or \"per_user_oauth\" (400 otherwise). Any provided\nfield replaces the stored value; no new config row is created and no\nre-discovery or re-registration runs. Unset fields preserve stored\nvalues: client_id/client_secret follow the SecretVar masked-placeholder\nconvention (send back the redacted placeholder from a GET response to\nkeep the stored secret), while empty strings / empty arrays on the\nremaining fields mean \"not provided\".\n\nWhen any field actually changes, every token bound to the OAuth config\nis flipped to needs_reauth regardless of auth mode, shared and\nper-user sessions alike must re-authenticate. A round trip that\nresolves to the stored values is a no-op and does not cascade.\nRotation cannot run while the client is (or is being) disabled\n(400); send those as two separate requests.\n" }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "Include-only list for tools.\n[\"*\"] => all tools are included\n[] => no tools are included\n[\"tool1\", \"tool2\"] => include only the specified tools\n" }, "tools_to_auto_execute": { "type": "array", "items": { "type": "string" }, "description": "List of tools that can be auto-executed without user approval.\nMust be a subset of tools_to_execute.\n[\"*\"] => all executable tools can be auto-executed\n[] => no tools are auto-executed\n[\"tool1\", \"tool2\"] => only specified tools can be auto-executed\n" }, "tool_pricing": { "type": "object", "additionalProperties": { "type": "number", "format": "double" }, "description": "Per-tool cost in USD for execution.\nKey is the tool name, value is the cost per execution.\nExample: {\"read_file\": 0.001, \"write_file\": 0.002}\nNote: Only available when updating an existing client after tools have been fetched.\n" }, "allow_on_all_virtual_keys": { "type": "boolean", "default": false, "description": "When true, this MCP client's tools are accessible to all virtual keys without requiring\nexplicit per-key assignment. All tools are allowed by default. If a virtual key has an\nexplicit MCP config for this client, that config takes precedence and overrides this behaviour.\n" }, "per_user_header_keys": { "type": "array", "items": { "type": "string" }, "description": "For `per_user_headers` clients only. Cannot be set to an empty list.\nUpdating this list flips every existing active per-user credential row\nto `needs_update`; callers will be sent back to the submission form on\ntheir next tool call to satisfy the new schema. The retained admin\ndiscovery credential is flipped the same way; repair it by calling\nPOST /api/mcp/client/{id}/verify-headers with fresh sample values.\n" }, "token_exchange": { "type": "object", "required": [ "audience" ], "properties": { "audience": { "type": "string", "minLength": 1, "description": "Resource identifier this server is scoped to at the identity provider (e.g. \"api://jira-mcp\")" }, "use_idp_credentials": { "type": "boolean", "description": "When true, performs the exchange as the SSO login application itself\ninstead of client_id/client_secret below, which are then ignored.\nSome providers require this: Microsoft Entra ID's on-behalf-of grant\nonly accepts an assertion audienced to the exchanging application,\nand the SSO login flow always requests a token self-audienced to the\nSSO application, so a separate exchange application can never\nreceive a usable one.\n" }, "client_id": { "type": "string", "minLength": 1, "description": "The identity-provider application authorized to perform exchanges for\nthis audience — typically a dedicated registration carrying the\ntoken-exchange (or on-behalf-of) grant, separate from the SSO login\napplication. Required unless use_idp_credentials is true. Supports\nenv.VAR_NAME and vault.path references. Redacted in API responses.\n" }, "client_secret": { "type": "string", "description": "Secret for the exchange application; omit for public clients. Ignored\nwhen use_idp_credentials is true. Supports env.VAR_NAME and\nvault.path references. Redacted in API responses.\n" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes to request on the exchanged token. Include\n\"offline_access\" (where the identity provider supports it) so the\nretained admin discovery credential gets a refresh token and stays\nself-renewing.\n" }, "authorization_server_url": { "type": "string", "description": "Overrides the Authorization Server the exchange request is sent to.\nOnly needed when the audience is registered on a different\nAuthorization Server than the one used for SSO login (e.g. Okta's\nper-resource Custom Authorization Servers). Leave unset to use the\ndeployment's SSO login issuer, which is correct for providers with a\nsingle tenant-wide token endpoint (Entra, Auth0).\n" } }, "allOf": [ { "if": { "not": { "properties": { "use_idp_credentials": { "const": true } }, "required": [ "use_idp_credentials" ] } }, "then": { "required": [ "client_id" ], "description": "client_id is required unless use_idp_credentials is true, in which\ncase the exchange uses the SSO login application's own credentials\ninstead.\n" } } ], "additionalProperties": false, "description": "For `token_exchange` clients only. Omitted preserves the stored\nconfiguration. A redacted `client_id` / `client_secret` round-tripped\nfrom a prior GET is resolved back to the stored value rather than\noverwriting it; any other change re-scopes future exchanges and\ninvalidates cached exchanged tokens for this client.\n" }, "disabled": { "type": "boolean", "default": false, "description": "When true, the client's connection, health monitor, and tool syncer are shut down.\nThe client entry is preserved so it can be re-enabled later by sending disabled: false.\nDisabled clients do not expose tools to inference requests.\n" }, "tls_config": { "type": "object", "description": "TLS configuration for HTTP and SSE connections.\nNot applicable to stdio or inprocess connection types.\n", "properties": { "insecure_skip_verify": { "type": "boolean", "description": "Disable TLS certificate verification. Takes priority over ca_cert_pem when both are set.\nUse only in development or trusted isolated environments. Not recommended for production.\n" }, "ca_cert_pem": { "type": "string", "description": "PEM-encoded CA certificate to trust for MCP server connections.\nUse when the MCP server uses a self-signed or private CA certificate.\nSupports env.VAR_NAME syntax to read the certificate from an environment variable.\n" } } }, "vk_configs": { "type": "array", "items": { "type": "object", "description": "Per-virtual-key tool access configuration for an MCP client", "required": [ "virtual_key_id", "tools_to_execute" ], "properties": { "virtual_key_id": { "type": "string", "description": "ID of the virtual key" }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "Tools this virtual key is allowed to call on this MCP server.\n[\"*\"] => all tools allowed\n[\"tool1\", \"tool2\"] => only the specified tools\n" } } }, "description": "When provided, replaces all virtual key assignments for this MCP client.\nEach entry specifies a virtual key and the tools it is allowed to call.\nTo remove all VK access, provide an empty array [].\nOmit this field to leave existing VK assignments unchanged.\n" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP client updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "removeMCPClient", "summary": "Remove MCP client", "description": "Removes an MCP client from the configuration.", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP client ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP client removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client/{id}/reconnect": { "post": { "operationId": "reconnectMCPClient", "summary": "Reconnect MCP client", "description": "Reconnects an MCP client that is in an error or unstable state.\nNot applicable (400) to any per-call client — a shared client running\nper-call (needs_session_stickiness false/omitted) as well as any\nper-user auth type — since none of them hold a shared upstream\nconnection to re-establish. Also not applicable to clients in\npending_verification state — complete the admin verification instead.\n", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP client ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP client reconnected successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client/{id}/complete-oauth": { "post": { "operationId": "completeMCPClientOAuth", "summary": "Complete MCP client OAuth flow", "description": "Completes an OAuth flow for an MCP client after the admin has authorized\nthe request upstream. Call it once the flow's status_url reports\n\"authorized\". It serves every admin-side OAuth completion with one\nendpoint:\n\n- Create-time and config.json-bootstrap flows: retrieves the pending MCP\n client configuration and establishes the connection with the\n OAuth-provided credentials (per_user_oauth clients instead verify with\n the admin token, discover tools, and retain the token as the admin\n discovery credential).\n- Reauthorize flows (started via POST /api/mcp/client/{id}/reauthorize):\n for shared \"oauth\" clients, reconnects the client with the fresh\n credential; for per_user_oauth clients, verifies the fresh admin token\n upstream, re-discovers tools, and promotes it to the retained admin\n discovery credential.\n\nReplays are rejected with 409: hitting the endpoint again after the flow\nalready completed (no pending configuration and no freshly-written\ntoken) returns \"OAuth flow has already been completed\". A shared\n\"oauth\" reauthorize is also rejected with 409 if its flow never\nactually resolved via a real callback — e.g. the upstream authorization\nserver rejected the request outright before ever redirecting back —\nreturning \"Authorization has not completed yet\". This is detected via\nthe flow's own row rather than the client's overall OAuth status,\nwhich never regresses once a client has been authorized once and so\ncan't distinguish a stale prior authorization from a fresh one.\n", "tags": [ "MCP", "OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The oauth_config_id of the flow being completed (as returned in the\ninitiation response's oauth_config_id / complete_url), not the MCP\nclient ID.\n", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP client connected (or re-authorized) successfully with OAuth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "OAuth flow not authorized yet, or the OAuth config does not belong to an OAuth-based MCP client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "OAuth config not found, or no MCP client is linked to this OAuth flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "Either \"OAuth flow has already been completed for this MCP client\"\n(replay), or \"Authorization has not completed yet: the browser\nflow may still be open, or the upstream provider rejected it\nbefore redirecting back\" (a shared \"oauth\" reauthorize whose flow\nnever actually resolved via a callback).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client/{id}/initiate-verification": { "post": { "operationId": "initiateMCPClientVerification", "summary": "Initiate verification for a pending MCP client", "description": "Starts the one-time admin OAuth authorization for an MCP client sitting\nin pending_verification state (declared via config.json with auth_type\n\"oauth\" or \"per_user_oauth\"). Runs OAuth metadata discovery (RFC 8414)\nand dynamic client registration (RFC 7591) against the client's\nconnection_string when the declared oauth_config omits those fields,\ncreates a fresh OAuth flow, and returns the authorization URL.\n\nComplete the flow like a create-time OAuth flow: open authorize_url in a\nbrowser, poll status_url until \"authorized\", then POST complete_url.\nSafe to call again if a previous attempt expired or was abandoned — each\ncall starts a fresh flow.\n", "tags": [ "MCP", "OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP client ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "OAuth flow initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthFlowInitiation" } } } }, "400": { "description": "Client is not in pending_verification state, is not an OAuth-based auth type, has no pending bootstrap configuration, or has no connection_string", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client/{id}/reauthorize": { "post": { "operationId": "reauthorizeMCPClient", "summary": "Reauthorize an MCP client", "description": "Redoes the OAuth consent flow for an already-authorized OAuth-based MCP\nclient, without delete-and-recreate. The flow always runs against the\ncredentials currently stored on the client's OAuth config.\n\n- auth_type \"oauth\": serves both a standalone admin-triggered reauth\n (e.g. the upstream provider revoked the credential and the client sits\n in needs_reauth) and the follow-up to rotating oauth_config via\n PUT /api/mcp/client/{id} (which cascades every bound token to\n needs_reauth).\n- auth_type \"per_user_oauth\": repairs the retained admin discovery\n credential used for periodic tool-list refresh. Only allowed while\n that credential actually sits in needs_reauth (409 otherwise);\n end-user credentials are untouched either way.\n\nComplete the returned flow like any other admin OAuth flow: open\nauthorize_url in a browser, poll status_url until \"authorized\", then\nPOST complete_url.\n", "tags": [ "MCP", "OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP client ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Reauthorization flow initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthFlowInitiation" } } } }, "400": { "description": "Client is not an OAuth-based auth type (oauth, per_user_oauth), or has never completed initial OAuth authorization (use initiate-verification instead)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "MCP client not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "The admin discovery credential for this per_user_oauth client does not need repair or does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client/{id}/verify-headers": { "post": { "operationId": "verifyMCPClientHeaders", "summary": "Verify a pending per-user-headers MCP client", "description": "Completes the admin verification for an MCP client with auth_type\n\"per_user_headers\". The admin supplies sample values for every declared\nper_user_header_keys entry; Bifrost opens an upstream connection with\nthem, discovers the tool list, persists it, and transitions the client\nto connected. The sample values are retained as the admin discovery\ncredential the periodic tool syncer uses to refresh the tool list; each\nend-user still submits their own values at runtime. Synchronous; no\nbrowser flow.\n\nServes two situations: the one-time bootstrap verification for a client\nsitting in pending_verification (declared via config.json), and a\nvoluntary refresh of an already-verified client's retained admin\ndiscovery credential — resubmitting sample values always re-runs\nverification and upserts the credential back to active, whether or not\nit currently needs repair (mirrors POST /reauthorize for OAuth-based\nclients).\n", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP client ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_headers" ], "properties": { "user_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Sample value for every header name declared in the client's\nper_user_header_keys. Used for the verification connection,\nthen retained as the admin discovery credential for periodic\ntool-list refresh. Never used for end-user traffic and never\nsurfaced on /api/mcp/sessions.\n" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Client verified; tools discovered and client connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "tools_count": { "type": "integer", "description": "Number of tools discovered during verification" } } } } } }, "400": { "description": "Client is not auth_type \"per_user_headers\", has no per_user_header_keys declared, or user_headers is missing required keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "422": { "description": "Upstream verification failed with the supplied header values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client/{id}/verify-exchange": { "post": { "operationId": "verifyMCPClientExchange", "summary": "Verify a pending or repair a needs_reauth token_exchange MCP client", "description": "Completes admin verification for an MCP client with auth_type\n\"token_exchange\". No request body: the subject of the exchange is\nalways the signed-in admin's own identity-provider token (from an SSO\nsession or an identity-authenticated bearer request) — there is no\nmanual token input. Bifrost exchanges it exactly like a real caller's\ntoken would be exchanged, opens an upstream connection with the result,\ndiscovers the tool list, persists it, and transitions the client to\nconnected. The exchanged token (and any refresh token the identity\nprovider issued alongside it) is retained as the admin discovery\ncredential the periodic tool syncer uses to refresh the tool list;\nend-user tool calls always exchange the caller's own token instead.\nSynchronous; no browser flow.\n\nServes two situations: the one-time bootstrap verification for a client\nsitting in pending_verification, and a voluntary refresh of an\nalready-verified client's retained admin discovery credential —\nresubmitting always re-runs verification and retains a fresh\ncredential, whether or not it currently needs repair (mirrors POST\n/reauthorize for OAuth-based clients).\n", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP client ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Client verified; tools discovered and client connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "tools_count": { "type": "integer", "description": "Number of tools discovered during verification" } } } } } }, "400": { "description": "Client is not auth_type \"token_exchange\", token exchange is\nunavailable (no identity-provider integration configured), or the\nrequest carries no identity-provider token to exchange (sign in\nwith your identity provider and retry)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "422": { "description": "The identity provider rejected the exchange, or the upstream verification connection failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/sessions": { "get": { "summary": "List MCP sessions", "description": "Returns every per-user MCP authentication artifact visible to the caller:\nOAuth tokens, header credentials, and pending submission / consent flows.\n\nRow visibility is scoped to the caller's identity (Virtual Key, signed-in\nuser, or asserted session ID). Server-level `headers` / `oauth` clients\nare not surfaced here; their credentials live on the MCP client config.\nAdmin discovery credentials (the retained bootstrap credential Bifrost\nuses for periodic tool-list refresh on per-user clients) never appear\nhere either; only user-, vk-, and session-keyed rows are listed.\n\nWhen both a credential and a pending flow exist for the same\n`(identity, mcp_client)` binding, the credential is returned and the\nflow is suppressed to avoid duplicate entries.\n", "operationId": "listMcpSessions", "tags": [ "MCP" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Sessions visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPSessionsListResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/sessions/{id}": { "delete": { "summary": "Revoke an MCP session", "description": "Revokes a session by primary key. Accepts these row kinds:\n- OAuth token rows → hard-deletes the token plus any pending OAuth flow\n for the same binding (so an in-flight callback can't undo the revoke)\n- Header credential rows → hard-deletes the credential plus any pending\n header submission flow for the same binding\n- Pending per-user-headers flow rows → hard-deletes just the flow\n\nNote: pending per-user OAuth flow rows are **not** revocable by this\nendpoint — they expire naturally or are cleared when the bound token\nrow is revoked. To cancel a pending OAuth flow, revoke its parent token\n(if one exists) or wait for expiry.\n\nBifrost does **not** call the upstream provider's revoke endpoint —\nrevocation is local. Per-user-headers credentials never call upstream.\n", "operationId": "revokeMcpSession", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session / credential / flow row ID" } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "204": { "description": "Revoked" }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/sessions/{id}/reauth": { "post": { "summary": "Re-authenticate or edit an MCP session", "description": "Mints a fresh authentication flow against the same MCP client and identity\nas the existing row. Two branches based on row type:\n\n- **OAuth token** (any non-`orphaned` row, typically `needs_reauth` —\n but `active` is also accepted) — opens a fresh upstream OAuth consent\n flow. Caller is expected to follow `authorize_url` to the provider;\n on callback the credential is replaced in place.\n- **Header credential** (`active` or `needs_update`) — opens a fresh\n per-user-headers submission flow. Caller follows the same URL field\n to the Bifrost submission form; on submit the credential is replaced\n in place. `kind: \"headers\"` is set on the response.\n\nRefused with 403 if the row is `orphaned` — a fresh credential wouldn't\nhelp; the issue is the identity has lost access to the MCP, which the\nadmin must fix.\n", "operationId": "reauthMcpSession", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session row ID (OAuth token or header credential)" } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Fresh flow opened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPSessionReauthResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "403": { "description": "Row is orphaned — re-auth would not restore access" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/per-user-headers/flows/{id}": { "get": { "summary": "Get per-user-headers submission flow", "description": "Returns the pending submission flow row plus the live MCP client's schema\n(required header names + optional admin header names). Used by the\n`/workspace/mcp-sessions/auth?flow=&kind=headers` landing page to\nrender the values form.\n\nRequires management API authentication via `Authorization: Bearer `.\n", "operationId": "getPerUserHeadersFlow", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Flow row ID" } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Flow detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPHeadersFlowDetail" } } } }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "summary": "Submit per-user-headers values", "description": "Consumes a pending submission flow row: verifies the caller's values\nagainst the upstream MCP server, upserts the credential keyed by the flow\nrow's (mode, identity), then deletes the flow row and the bound temp\ntoken. Mirrors the OAuth callback's \"complete the flow\" semantics.\n\nValues for any key not in the live `per_user_header_keys` schema are\ndropped server-side so a stale UI can't persist deprecated keys.\n", "operationId": "submitPerUserHeadersFlow", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Flow row ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPHeadersSubmitRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Credential persisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPHeadersSubmitResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "410": { "description": "Flow expired" }, "422": { "description": "Upstream verification failed with the supplied values" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/per-user-headers/credential/{id}": { "delete": { "summary": "Revoke a per-user-headers credential", "description": "Hard-deletes a per-user-headers credential row by primary key. Authorization\nscoping is enforced server-side — callers may only delete credentials\nvisible to their identity.\n\nThe unified DELETE /api/mcp/sessions/{id} is the more convenient entry\npoint; this typed endpoint exists for callers that already know they're\nacting on a header credential row.\n", "operationId": "revokePerUserHeadersCredential", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Credential row primary key" } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "204": { "description": "Revoked" }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/oauth/per-user/flows/{id}": { "get": { "operationId": "getPerUserOauthFlow", "summary": "Get per-user OAuth flow detail", "description": "Returns the pending OAuth flow row metadata: which MCP client is being\nauthorized, which identity (user / VK / session) the resulting token\nwill be bound to, and whether an active token already exists for that\nbinding (`has_active_token`).\n\nRequires management API authentication via `Authorization: Bearer `.\n", "tags": [ "OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow row ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Flow detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPOauthFlowDetail" } } } }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/oauth/per-user/flows/{id}/start": { "get": { "operationId": "startPerUserOauthFlow", "summary": "Start the upstream OAuth authorization for a pending flow", "description": "Reconstructs the upstream provider's authorize URL for a pending OAuth\nflow. The auth-landing page redirects the browser to that URL; the user\ncompletes upstream auth; the upstream provider redirects back to\n`/api/oauth/callback`, which exchanges the code for tokens server-side\nand stores them against the flow's identity.\n\nReturns 410 if the flow is no longer pending (expired / completed /\nfailed). The caller should restart the original action to get a fresh\nflow.\n", "tags": [ "OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow row ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Authorize URL", "content": { "application/json": { "schema": { "type": "object", "required": [ "authorize_url" ], "properties": { "authorize_url": { "type": "string", "description": "Where to send the browser to complete upstream OAuth" } } } } } }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "410": { "description": "Flow is no longer pending; restart the original action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/oauth/callback": { "get": { "operationId": "handleOAuthCallback", "summary": "OAuth callback endpoint", "description": "Handles the OAuth provider callback after user authorization.\nThis endpoint processes the authorization code and exchanges it for an access token.\nOn success, displays an HTML page that closes the authorization window.\n", "tags": [ "OAuth" ], "parameters": [ { "name": "state", "in": "query", "required": true, "description": "State parameter for OAuth security (CSRF protection)", "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "description": "Authorization code from the OAuth provider. Present on success only;\n`code` and `error` are mutually exclusive — one of them is always set.\n", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Error code if authorization failed. Mutually exclusive with `code`.\n", "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "description": "Error description if authorization failed", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "OAuth authorization successful. Returns HTML page that closes the authorization window.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "OAuth authorization failed or missing required parameters", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/api/oauth/config/{id}/status": { "get": { "operationId": "getOAuthConfigStatus", "summary": "Get OAuth config status", "description": "Retrieves the current status of an OAuth configuration.\nShows whether the OAuth flow is pending, authorized, or failed,\nand includes token expiration and scopes if authorized.\n", "tags": [ "OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "OAuth config ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "OAuth config status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthConfigStatus" } } } }, "404": { "description": "OAuth config not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/oauth/config/{id}": { "delete": { "operationId": "revokeOAuthConfig", "summary": "Revoke OAuth config", "description": "Revokes a server-level OAuth configuration and its associated access token.\nAfter revocation, the MCP client will no longer be able to use this OAuth token.\nRevocation is not terminal for the client: an admin can restore access by\nredoing consent via POST /api/mcp/client/{id}/reauthorize, which runs\nagainst the credentials currently stored on the client's OAuth config.\n", "tags": [ "OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "OAuth config ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "OAuth token revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/virtual-keys": { "get": { "operationId": "listVirtualKeys", "summary": "List virtual keys", "description": "Returns a list of all virtual keys with their configurations.", "tags": [ "Governance" ], "parameters": [ { "name": "from_memory", "in": "query", "description": "If true, returns virtual keys from in-memory cache instead of database. Filtering, sorting and pagination parameters are not applied in this mode; combining it with user_id is rejected with a 400.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Maximum number of virtual keys to return", "schema": { "type": "integer", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Number of virtual keys to skip", "schema": { "type": "integer", "minimum": 0 } }, { "name": "search", "in": "query", "description": "Case-insensitive search by virtual key name", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Filter virtual keys by customer ID", "schema": { "type": "string" } }, { "name": "team_id", "in": "query", "description": "Filter virtual keys by team ID", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Filter virtual keys by assigned user ID (enterprise only; matches no virtual keys on OSS builds). Combined with customer_id/team_id using OR.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "schema": { "type": "string", "enum": [ "name", "budget_spent", "created_at", "status" ] } }, { "name": "order", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "export", "in": "query", "description": "If true, enables export pagination limits", "schema": { "type": "boolean", "default": false } }, { "name": "exclude_access_profile_managed_virtual", "in": "query", "description": "If true, excludes virtual keys managed by access profiles", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVirtualKeysResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createVirtualKey", "summary": "Create virtual key", "description": "Creates a new virtual key with the specified configuration.", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVirtualKeyRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual key created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualKeyResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/virtual-keys/quota": { "get": { "operationId": "getVirtualKeyQuota", "summary": "Get virtual key quota", "description": "Returns the overall budget and rate limit quota for the authenticated virtual key,\nas well as per-provider and per-model budgets and rate limits (with current usage).\nEach budget also carries the actual per-model usage for its current cycle.\nThis is a self-service endpoint - no admin authentication required.\nThe virtual key value itself (provided via header) is the credential.\n", "tags": [ "Governance" ], "security": [ { "VirtualKeyAuth": [] }, { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualKeyQuotaResponse" } } } }, "401": { "description": "Missing or invalid virtual key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/virtual-keys/{vk_id}": { "get": { "operationId": "getVirtualKey", "summary": "Get virtual key", "description": "Returns a specific virtual key by ID.", "tags": [ "Governance" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "description": "Virtual key ID", "schema": { "type": "string" } }, { "name": "from_memory", "in": "query", "description": "If true, returns virtual key from in-memory cache instead of database", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "virtual_key" ], "properties": { "virtual_key": { "$ref": "#/components/schemas/VirtualKey" } } } } } }, "404": { "description": "Virtual key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateVirtualKey", "summary": "Update virtual key", "description": "Updates an existing virtual key's configuration.", "tags": [ "Governance" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "description": "Virtual key ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVirtualKeyRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual key updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualKeyResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Virtual key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteVirtualKey", "summary": "Delete virtual key", "description": "Deletes a virtual key.", "tags": [ "Governance" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "description": "Virtual key ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual key deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Virtual key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/virtual-keys/{vk_id}/budgets/{budget_id}/override": { "put": { "operationId": "updateVirtualKeyBudgetOverride", "summary": "Set virtual key budget override", "description": "Sets or replaces the spending override on one of a virtual key's budgets. The override is additive —\nwhile it is active the budget is enforced against `max_limit + override_amount` — and it leaves the\nbudget's base limit, current usage, and reset schedule untouched.\n\nUse `mode: cycles` with a `cycles` count to grant extra spend for a finite number of reset windows\n(the current window counts as the first), or `mode: forever` to keep the override until it is deleted.\nA finite grant is anchored to the budget's current reset window, so every node in a cluster derives the\nsame number of remaining cycles and a config reload cannot resurrect a spent one.\n", "tags": [ "Governance" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "description": "Virtual key ID", "schema": { "type": "string" } }, { "name": "budget_id", "in": "path", "required": true, "description": "ID of a budget owned by the virtual key", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Budget override applied successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Virtual key or budget not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteVirtualKeyBudgetOverride", "summary": "Remove virtual key budget override", "description": "Removes any active override from the budget, so it is enforced against its base `max_limit` again.\nThe budget's current usage and reset schedule are unchanged, and the removal is permanent — a cleared\ngrant cannot be re-derived. Safe to call on a budget that has no override.\n", "tags": [ "Governance" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "description": "Virtual key ID", "schema": { "type": "string" } }, { "name": "budget_id", "in": "path", "required": true, "description": "ID of a budget owned by the virtual key", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Budget override removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideResponse" } } } }, "404": { "description": "Virtual key or budget not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/virtual-keys/{vk_id}/users": { "get": { "operationId": "listVirtualKeyUsers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List users attached to a virtual key", "tags": [ "Virtual Keys", "Users" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Attached users", "content": { "application/json": { "schema": { "type": "object", "required": [ "users", "count" ], "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "count": { "type": "integer" } } } } } } } }, "post": { "operationId": "attachVirtualKeyUsers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Attach users to a virtual key", "tags": [ "Virtual Keys", "Users" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_ids" ], "properties": { "user_ids": { "type": "array", "items": { "type": "string" } }, "preserve_usage": { "type": "boolean", "default": false } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Users attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/virtual-keys/{vk_id}/users/{user_id}": { "delete": { "operationId": "detachVirtualKeyUser", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach a user from a virtual key", "tags": [ "Virtual Keys", "Users" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "User detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/virtual-keys/rotate": { "post": { "operationId": "bulkRotateVirtualKeys", "summary": "Rotate multiple virtual keys", "description": "Generates a new value for each listed virtual key. When the client vk_rotation_cooldown setting is non-zero, each retired value keeps authenticating until previous_value_expires_at; otherwise it stops working immediately.", "tags": [ "Governance" ], "security": [ { "ManagementBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "description": "IDs of the virtual keys to rotate (duplicates are ignored)", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Virtual keys rotated (partial failures reported per ID in errors)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "virtual_keys" ], "properties": { "message": { "type": "string" }, "virtual_keys": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualKey" } }, "errors": { "type": "object", "description": "Map of virtual key ID to failure reason for keys that could not be rotated", "additionalProperties": { "type": "string" } } } } } } }, "400": { "description": "Invalid request (empty or missing IDs)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "All requested rotations failed; per-ID reasons are reported in errors", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "virtual_keys", "errors" ], "properties": { "message": { "type": "string" }, "virtual_keys": { "type": "array", "description": "Always empty when every rotation failed", "items": { "$ref": "#/components/schemas/VirtualKey" } }, "errors": { "type": "object", "description": "Map of virtual key ID to failure reason", "additionalProperties": { "type": "string" } } } } } } } } } }, "/api/governance/virtual-keys/{vk_id}/rotate": { "post": { "operationId": "rotateVirtualKey", "summary": "Rotate virtual key", "description": "Generates a new value for the virtual key. When the client vk_rotation_cooldown setting is non-zero, the retired value keeps authenticating until previous_value_expires_at; otherwise it stops working immediately.", "tags": [ "Governance" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "description": "Virtual key ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual key rotated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "virtual_key" ], "properties": { "message": { "type": "string" }, "virtual_key": { "$ref": "#/components/schemas/VirtualKey" } } } } } }, "404": { "description": "Virtual key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/teams": { "get": { "operationId": "listTeams", "summary": "List teams", "description": "Returns a list of all teams.", "tags": [ "Governance" ], "parameters": [ { "name": "customer_id", "in": "query", "description": "Filter teams by customer ID", "schema": { "type": "string" } }, { "name": "from_memory", "in": "query", "description": "If true, returns teams from in-memory cache instead of database", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTeamsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createTeam", "summary": "Create team", "description": "Creates a new team.", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Team created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/teams/{team_id}": { "get": { "operationId": "getTeam", "summary": "Get team", "description": "Returns a specific team by ID.", "tags": [ "Governance" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } }, { "name": "from_memory", "in": "query", "description": "If true, returns team from in-memory cache instead of database", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" } } } } } }, "404": { "description": "Team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateTeam", "summary": "Update team", "description": "Updates an existing team.", "tags": [ "Governance" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Team updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteTeam", "summary": "Delete team", "description": "Deletes a team.", "tags": [ "Governance" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Team deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/teams/{team_id}/customers": { "get": { "operationId": "listTeamCustomers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List customers attached to a team", "tags": [ "Teams", "Customers" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Attached customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } }, "post": { "operationId": "attachTeamCustomer", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Attach a customer to a team", "tags": [ "Teams", "Customers" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customer attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/teams/{team_id}/customers/{customer_id}": { "delete": { "operationId": "detachTeamCustomer", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach a customer from a team", "tags": [ "Teams", "Customers" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customer detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/customers": { "get": { "operationId": "listCustomers", "summary": "List customers", "description": "Returns a list of all customers.", "tags": [ "Governance" ], "parameters": [ { "name": "from_memory", "in": "query", "description": "If true, returns customers from in-memory cache instead of database", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCustomersResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createCustomer", "summary": "Create customer", "description": "Creates a new customer.", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/customers/{customer_id}": { "get": { "operationId": "getCustomer", "summary": "Get customer", "description": "Returns a specific customer by ID.", "tags": [ "Governance" ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string" } }, { "name": "from_memory", "in": "query", "description": "If true, returns customer from in-memory cache instead of database", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } } } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateCustomer", "summary": "Update customer", "description": "Updates an existing customer.", "tags": [ "Governance" ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteCustomer", "summary": "Delete customer", "description": "Deletes a customer.", "tags": [ "Governance" ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customer deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/customers/{customer_id}/teams": { "get": { "operationId": "listCustomerTeams", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List teams attached to a customer", "tags": [ "Customers", "Teams" ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Attached teams", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } } }, "/api/governance/customers/{customer_id}/business-units": { "get": { "operationId": "listCustomerBusinessUnits", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List business units attached to a customer", "tags": [ "Customers", "Business Units" ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Attached business units", "content": { "application/json": { "schema": { "type": "object", "properties": { "business_units": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } } }, "/api/governance/business-units": { "get": { "operationId": "listBusinessUnits", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List business units", "description": "Returns a paginated list of business units, each with its team count.", "tags": [ "Governance" ], "parameters": [ { "name": "offset", "in": "query", "description": "Zero-based result offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of business units to return (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "search", "in": "query", "description": "Case-insensitive search by business unit name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated list of business units", "required": [ "business_units", "count", "total_count", "limit", "offset" ], "properties": { "business_units": { "type": "array", "items": { "type": "object", "description": "Business unit summary as returned in list responses", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "team_count": { "type": "integer" }, "customer_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" }, "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createBusinessUnit", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create business unit", "description": "Creates a new business unit. Names must be unique.", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create business unit request", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Business unit created successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Response for business unit create/update operations", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "A business unit with this name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/business-units/{business_unit_id}": { "get": { "operationId": "getBusinessUnit", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get business unit", "description": "Returns a specific business unit by ID, including governance and team count.", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Single business unit with governance and team count", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "team_count": { "type": "integer" }, "budget": { "$ref": "#/components/schemas/Budget" }, "rate_limit": { "$ref": "#/components/schemas/RateLimit" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Business unit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateBusinessUnit", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update business unit", "description": "Updates the business unit name.", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create business unit request", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Business unit updated successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Response for business unit create/update operations", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "A business unit with this name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteBusinessUnit", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete business unit", "description": "Deletes a business unit. Any teams assigned to it are atomically unassigned\nas part of the deletion.\n", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Business unit deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Business unit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/business-units/{business_unit_id}/teams": { "get": { "operationId": "listBusinessUnitTeams", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List business unit teams", "description": "Returns a paginated list of teams assigned to the business unit.", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Zero-based result offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of teams to return (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "search", "in": "query", "description": "Case-insensitive search by team name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated list of teams assigned to a business unit", "required": [ "teams", "count", "total_count", "limit", "offset" ], "properties": { "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "count": { "type": "integer" }, "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "404": { "description": "Business unit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "assignTeamToBusinessUnit", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Assign team to business unit", "description": "Assigns an existing team to the business unit. Returns 409 if the team is\nalready assigned to a different business unit.\n", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request to assign a team to a business unit", "required": [ "team_id" ], "properties": { "team_id": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Team assigned to business unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Business unit or team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "409": { "description": "Team is already assigned to another business unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/business-units/{business_unit_id}/teams/{team_id}": { "delete": { "operationId": "removeTeamFromBusinessUnit", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Remove team from business unit", "description": "Unassigns a team from the business unit.", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } }, { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Team removed from business unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Business unit or team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/business-units/{business_unit_id}/governance": { "post": { "operationId": "createBusinessUnitGovernance", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create business unit governance", "description": "Configures budget and/or rate limit governance for a business unit. At least\none of `budget` or `rate_limit` is required. Returns 409 if the business unit\nalready has governance configured (use PUT to update).\n", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create business unit governance request. The business unit is identified by\nthe {id} path parameter. At least one of budget or rate_limit is required.\n", "anyOf": [ { "required": [ "budget" ] }, { "required": [ "rate_limit" ] } ], "properties": { "budget": { "$ref": "#/components/schemas/CreateBudgetRequest" }, "rate_limit": { "$ref": "#/components/schemas/CreateRateLimitRequest" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Business unit governance created successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Business unit governance operation response", "properties": { "message": { "type": "string" }, "business_unit": { "type": "object", "description": "Business unit configuration with governance association", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source_id": { "type": "string", "description": "External source identifier (e.g. from SCIM provisioning)" }, "profile": { "type": "object", "additionalProperties": true, "nullable": true }, "config": { "type": "object", "additionalProperties": true, "nullable": true }, "claims": { "type": "object", "additionalProperties": true, "nullable": true }, "budget_id": { "type": "string" }, "rate_limit_id": { "type": "string" }, "budget": { "$ref": "#/components/schemas/Budget" }, "rate_limit": { "$ref": "#/components/schemas/RateLimit" }, "config_hash": { "type": "string" }, "created_by_user_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Business unit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "409": { "description": "Business unit already has governance configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateBusinessUnitGovernance", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update business unit governance", "description": "Updates budget and/or rate limit governance for a business unit. Passing an\nempty `budget` or `rate_limit` object removes that governance component.\n", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Update business unit governance request. Passing an empty budget or rate_limit\nobject removes that governance component.\n", "properties": { "budget": { "$ref": "#/components/schemas/UpdateBudgetRequest" }, "rate_limit": { "$ref": "#/components/schemas/UpdateRateLimitRequest" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Business unit governance updated successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Business unit governance operation response", "properties": { "message": { "type": "string" }, "business_unit": { "type": "object", "description": "Business unit configuration with governance association", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source_id": { "type": "string", "description": "External source identifier (e.g. from SCIM provisioning)" }, "profile": { "type": "object", "additionalProperties": true, "nullable": true }, "config": { "type": "object", "additionalProperties": true, "nullable": true }, "claims": { "type": "object", "additionalProperties": true, "nullable": true }, "budget_id": { "type": "string" }, "rate_limit_id": { "type": "string" }, "budget": { "$ref": "#/components/schemas/Budget" }, "rate_limit": { "$ref": "#/components/schemas/RateLimit" }, "config_hash": { "type": "string" }, "created_by_user_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Business unit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteBusinessUnitGovernance", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete business unit governance", "description": "Removes all budget and rate limit governance from a business unit.", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Business unit governance deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Business unit not found or has no governance configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/business-units/{business_unit_id}/customers": { "get": { "operationId": "listBusinessUnitCustomers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List customers attached to a business unit", "tags": [ "Business Units", "Customers" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Attached customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "count": { "type": "integer" }, "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "post": { "operationId": "attachBusinessUnitCustomer", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Attach customers to a business unit", "tags": [ "Business Units", "Customers" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string" }, "customer_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customers attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/business-units/{business_unit_id}/customers/{customer_id}": { "delete": { "operationId": "detachBusinessUnitCustomer", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach a customer from a business unit", "tags": [ "Business Units", "Customers" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customer detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/budgets": { "get": { "operationId": "listBudgets", "summary": "List budgets", "description": "Returns a list of all budgets. Use the `from_memory` query parameter to get data from in-memory cache.", "tags": [ "Governance" ], "parameters": [ { "name": "from_memory", "in": "query", "description": "If true, returns budgets from in-memory cache instead of database", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBudgetsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/rate-limits": { "get": { "operationId": "listRateLimits", "summary": "List rate limits", "description": "Returns a list of all rate limits. Use the `from_memory` query parameter to get data from in-memory cache.", "tags": [ "Governance" ], "parameters": [ { "name": "from_memory", "in": "query", "description": "If true, returns rate limits from in-memory cache instead of database", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRateLimitsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/model-configs": { "get": { "operationId": "listModelConfigs", "summary": "List model limits", "description": "Returns a paginated list of model limits with their budget and rate limit settings.", "tags": [ "Governance" ], "security": [ { "ManagementBearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results to return", "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of results to skip (for pagination)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "search", "in": "query", "description": "Case-insensitive filter by model name", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "Filter by scope (`global`, `virtual_key`, or `user`; `user` is Enterprise only)", "schema": { "type": "string", "enum": [ "global", "virtual_key", "user" ] } }, { "name": "provider", "in": "query", "description": "Filter by provider name", "schema": { "type": "string" } }, { "name": "from_memory", "in": "query", "description": "If true, returns data from in-memory cache (faster, may lag DB by one poll cycle)", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelConfigsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createModelConfig", "summary": "Create model config", "description": "Creates a new model configuration with budget and rate limit settings.", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModelConfigRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Model config created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/model-configs/{mc_id}": { "get": { "operationId": "getModelConfig", "summary": "Get model config", "description": "Returns a specific model configuration by ID.", "tags": [ "Governance" ], "parameters": [ { "name": "mc_id", "in": "path", "required": true, "description": "Model config ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "model_config": { "$ref": "#/components/schemas/ModelConfig" } } } } } }, "404": { "description": "Model config not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateModelConfig", "summary": "Update model config", "description": "Updates an existing model configuration's budget and rate limit settings.", "tags": [ "Governance" ], "parameters": [ { "name": "mc_id", "in": "path", "required": true, "description": "Model config ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateModelConfigRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Model config updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Model config not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteModelConfig", "summary": "Delete model config", "description": "Deletes a model configuration.", "tags": [ "Governance" ], "parameters": [ { "name": "mc_id", "in": "path", "required": true, "description": "Model config ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Model config deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Model config not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/providers": { "get": { "operationId": "listProviderGovernance", "summary": "List provider governance", "description": "Returns a list of all providers with their governance settings (budget and rate limits).", "tags": [ "Governance" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProviderGovernanceResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/providers/{provider_name}": { "put": { "operationId": "updateProviderGovernance", "summary": "Update provider governance", "description": "Updates governance settings (budget and rate limits) for a specific provider.", "tags": [ "Governance" ], "parameters": [ { "name": "provider_name", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderGovernanceRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Provider governance updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderGovernanceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Provider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteProviderGovernance", "summary": "Delete provider governance", "description": "Removes governance settings (budget and rate limits) for a specific provider.", "tags": [ "Governance" ], "parameters": [ { "name": "provider_name", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Provider governance deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Provider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/pricing-overrides": { "get": { "operationId": "listPricingOverrides", "summary": "List pricing overrides", "description": "Returns all pricing overrides, optionally filtered by scope.", "tags": [ "Governance" ], "parameters": [ { "name": "scope_kind", "in": "query", "description": "Filter by scope kind", "schema": { "$ref": "#/components/schemas/PricingOverrideScopeKind" } }, { "name": "user_id", "in": "query", "description": "Filter by user ID (for user* scopes)", "schema": { "type": "string" } }, { "name": "virtual_key_id", "in": "query", "description": "Filter by virtual key ID (for virtual_key* scopes)", "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "description": "Filter by provider ID", "schema": { "type": "string" } }, { "name": "provider_key_id", "in": "query", "description": "Filter by provider key ID", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Case-insensitive substring match against the pricing override name. A non-empty value switches the response to the paginated shape.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return. A non-empty `limit`, `offset`, or `search` value switches the response to the paginated shape.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "minimum": 0 } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPricingOverridesResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createPricingOverride", "summary": "Create pricing override", "description": "Creates a new pricing override. The most specific matching scope always wins during cost resolution.", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePricingOverrideRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Pricing override created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingOverrideResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/pricing-overrides/{id}": { "put": { "operationId": "updatePricingOverride", "summary": "Update pricing override", "description": "Updates an existing pricing override. Omitted fields are merged from the existing record. The `patch` field is always replaced in full when provided.", "tags": [ "Governance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pricing override ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePricingOverrideRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Pricing override updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingOverrideResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Pricing override not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deletePricingOverride", "summary": "Delete pricing override", "description": "Deletes a pricing override by ID.", "tags": [ "Governance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pricing override ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Pricing override deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/rbac/roles": { "get": { "operationId": "listRoles", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List roles", "description": "Returns all roles visible to the caller, scoped by data access control.", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "description": "Lowercase letters, digits, `_`, `.`. Must start with a letter. Unique.", "maxLength": 255 }, "description": { "type": "string" }, "is_system_role": { "type": "boolean", "description": "True for built-in roles. System roles cannot be deleted." }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" }, "created_by_user_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createRole", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create role", "description": "Creates a custom role with the specified data access control scope.\nIf `dac` is omitted, defaults to `all-data`.\n", "tags": [ "RBAC" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Must match `^[a-z][a-z0-9_.]*$`. Max 255 characters. Unique.\n", "maxLength": 255 }, "description": { "type": "string" }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Defaults to `all-data` when omitted." } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role created", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "description": "Lowercase letters, digits, `_`, `.`. Must start with a letter. Unique.", "maxLength": 255 }, "description": { "type": "string" }, "is_system_role": { "type": "boolean", "description": "True for built-in roles. System roles cannot be deleted." }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" }, "created_by_user_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/rbac/roles/{role_id}": { "get": { "operationId": "getRole", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get role by ID", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "description": "Lowercase letters, digits, `_`, `.`. Must start with a letter. Unique.", "maxLength": 255 }, "description": { "type": "string" }, "is_system_role": { "type": "boolean", "description": "True for built-in roles. System roles cannot be deleted." }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" }, "created_by_user_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateRole", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update role", "description": "Partial update. Omitted fields preserve the current value.\nNotable: omitting `dac` preserves the current scope (does not default to `all-data`).\n", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update. Omitted fields preserve the current value.\n- `description` is a nullable string: omitting it preserves the existing description; sending an empty string clears it.\n- `dac` defaults to the existing value when omitted, preventing accidental scope escalation.\n", "properties": { "name": { "type": "string", "description": "If supplied (and different from current), must match the role-name regex.", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "description": "Lowercase letters, digits, `_`, `.`. Must start with a letter. Unique.", "maxLength": 255 }, "description": { "type": "string" }, "is_system_role": { "type": "boolean", "description": "True for built-in roles. System roles cannot be deleted." }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" }, "created_by_user_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteRole", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete role", "description": "Deletes a custom role. Built-in system roles cannot be deleted and return 403.\n", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "403": { "description": "Cannot delete system role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "cannot delete system role" } } } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/rbac/roles/{role_id}/permissions": { "get": { "operationId": "getRolePermissions", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List permissions assigned to a role", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "resource": { "type": "string" }, "operation": { "type": "string" } } } } } } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateRolePermissions", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Replace the permission set on a role", "description": "Replaces the permission set assigned to the role.\nSend the complete list of permission IDs that should be active for the role.\n", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "permission_ids" ], "properties": { "permission_ids": { "type": "array", "items": { "type": "integer", "format": "uint" } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Permissions updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/rbac/resources": { "get": { "operationId": "listResources", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List RBAC resources", "description": "Returns the set of resource names that permissions can target.", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/rbac/operations": { "get": { "operationId": "listOperations", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List RBAC operations", "description": "Returns the set of operation names that permissions can grant.", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/rbac/permissions": { "get": { "operationId": "listPermissions", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List all RBAC permissions", "description": "Returns every (resource, operation) pair that can be granted to a role.", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "resource": { "type": "string" }, "operation": { "type": "string" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles": { "get": { "operationId": "listAccessProfiles", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List access profiles", "description": "Returns access profiles visible to the caller.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Comma-separated list of tags to filter on.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" }, "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create access profile", "description": "Creates a new access profile template. The profile is inactive until attached to a role.\nNo size limits are enforced on create; the limits apply on update.\n", "tags": [ "Access Profiles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Profile created", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "A profile with the same name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}": { "get": { "operationId": "getAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get access profile by ID", "description": "Returns the profile plus its role attachments and the count of users holding a copy.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Returned by GET /api/access-profiles/{id}. Includes role attachments and the count of users holding a copy.", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "access_profile_id": { "type": "integer", "format": "uint" }, "role_id": { "type": "integer", "format": "uint" }, "role_name": { "type": "string" }, "is_default": { "type": "boolean" } } } }, "user_count": { "type": "integer" } } } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update access profile", "description": "Partial update. Omitted fields preserve the current value.\n`rate_limit: null` explicitly clears the existing rate limit.\nSize limits enforced: max 100 provider_configs, max 100 budgets, max 50 tags.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update. Omitted fields preserve the current value.\n`rate_limit: null` explicitly clears the existing rate limit; omitting the field preserves it.\nUpdate enforces size limits not enforced on create: max 100 provider_configs, max 100 budgets, max 50 tags.\n", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "nullable": true, "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } ] }, "calendar_aligned": { "type": "boolean", "nullable": true }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Profile not found" }, "409": { "description": "A profile with the same name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete access profile", "description": "Blocked with 409 if any users still hold copies. Detach role attachments or remove user assignments first.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Profile not found" }, "409": { "description": "Profile has active user copies; detach users first." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/activate": { "put": { "operationId": "activateAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Activate access profile", "description": "Sets the profile active. Idempotent.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile is active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/deactivate": { "put": { "operationId": "deactivateAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Deactivate access profile", "description": "Sets the profile inactive. Idempotent. User copies are preserved; the profile is hidden from selection menus.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile is inactive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/clone": { "post": { "operationId": "cloneAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Clone an access profile", "description": "Creates a fresh copy of the profile under a new name. The clone has no role attachments or user copies.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Cloned profile created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Source profile not found" }, "409": { "description": "A profile with the same name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/propagate": { "post": { "operationId": "propagateAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Propagate template changes to user copies", "description": "Pushes selected fields from the template to every user that holds a copy.\nUse `dry_run: true` to preview the impact. By default, accumulated usage is preserved.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fields" ], "properties": { "dry_run": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "provider_configs", "budgets", "rate_limit", "mcp_tool_groups", "mcp_servers", "mcp_tool_overrides" ] }, "minItems": 1 }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Empty or omitted = all users with a copy of this profile." }, "group_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by SCIM group or team IDs." }, "reset_usage": { "type": "boolean", "description": "If true, zero out budget and rate-limit usage on cloned rows. Default false (preserves usage)." } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Propagation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected_users": { "type": "integer" }, "failed_users": { "type": "integer" }, "skipped_users": { "type": "integer" }, "user_ids": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "array", "items": { "type": "string" } }, "applied": { "type": "boolean", "description": "False on dry run, true when changes were persisted." }, "vk_sync_errors": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/roles": { "post": { "operationId": "attachRolesToAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Attach roles to access profile", "description": "Attaches one or more roles. Setting `is_default: true` makes the profile the role's default\nfor new users. `apply_to_existing: true` provisions the profile to users already in the role.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role_ids" ], "properties": { "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint" }, "minItems": 1 }, "is_default": { "type": "boolean" }, "apply_to_existing": { "type": "boolean" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Roles attached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "users_applied": { "type": "integer" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/roles/{role_id}": { "delete": { "operationId": "detachRoleFromAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach role from access profile", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role detached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Role attachment not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/versions": { "get": { "operationId": "listAccessProfileVersions", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List version snapshots for an access profile", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "access_profile_id": { "type": "integer" }, "version": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "snapshot": { "type": "string", "description": "JSON snapshot of the profile at this version." }, "changed_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/versions/{version}": { "get": { "operationId": "getAccessProfileVersion", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get a single version snapshot", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "integer" }, "access_profile_id": { "type": "integer" }, "version": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "snapshot": { "type": "string", "description": "JSON snapshot of the profile at this version." }, "changed_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Version not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/{profile_id}/audit-logs": { "get": { "operationId": "listAccessProfileAuditLogsById", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List audit log entries for a single profile", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "description": "One of create, update, delete, propagate, attach_role, detach_role, clone, activate, deactivate.", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "access_profile_id": { "type": "integer", "nullable": true }, "user_id": { "type": "string", "nullable": true }, "actor": { "type": "string" }, "action": { "type": "string" }, "previous_values": { "type": "string", "nullable": true }, "new_values": { "type": "string", "nullable": true }, "metadata": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "total_count": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/access-profiles/audit-logs": { "get": { "operationId": "listAccessProfileAuditLogs", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List workspace-wide audit log entries", "tags": [ "Access Profiles" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "access_profile_id": { "type": "integer", "nullable": true }, "user_id": { "type": "string", "nullable": true }, "actor": { "type": "string" }, "action": { "type": "string" }, "previous_values": { "type": "string", "nullable": true }, "new_values": { "type": "string", "nullable": true }, "metadata": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "total_count": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/access-profiles": { "get": { "operationId": "listUserAccessProfiles", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List access profiles held by a user", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "virtual_key_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map of virtual key ID to masked secret value." } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/access-profiles/{profile_id}": { "delete": { "operationId": "detachUserAccessProfile", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach a user's access profile", "description": "Removes the profile from the user and deletes every virtual key it produced. Fails closed if a virtual key cannot be deleted.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile detached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "deleted_vk_names": { "type": "array", "items": { "type": "string" } }, "deleted_vk_count": { "type": "integer" } } } } } }, "404": { "description": "User access profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override": { "put": { "operationId": "updateUserAccessProfileBudgetOverride", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Set a user's access-profile budget override", "description": "Sets or replaces the spending override on one budget of a single user's copy of an access profile.\nThe override is additive — while it is active the budget is enforced against\n`max_limit + override_amount` — and it leaves the budget's base limit, current usage, and reset\nschedule untouched. Only this user is affected; the access profile template and every other user\nassigned to it keep their original limits.\n\nUse `mode: cycles` with a `cycles` count to grant extra spend for a finite number of reset windows\n(the current window counts as the first), or `mode: forever` to keep the override until it is deleted.\nA finite grant is anchored to the profile's reset window — calendar-aligned profiles anchor at the\ncalendar period start — so every node in a cluster derives the same number of remaining cycles.\nThe change is propagated cluster-wide and survives access-profile cloning and propagation.\n\nRequires the `AccessProfiles.Update` permission. `budget_id` must be a budget on the user's own copy\nof the profile, not on the shared template.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "ID of the user whose access-profile budget is being overridden", "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "description": "ID of the access profile assigned to the user", "schema": { "type": "integer" } }, { "name": "budget_id", "in": "path", "required": true, "description": "ID of a budget on the user's copy of the access profile", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Budget override applied successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User access profile or budget not found, or the profile is outside the caller's access scope" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteUserAccessProfileBudgetOverride", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Remove a user's access-profile budget override", "description": "Removes any active override from the user's budget, so it is enforced against its base `max_limit`\nagain. The budget's current usage and reset schedule are unchanged, and the removal is permanent — a\ncleared grant cannot be re-derived. Safe to call on a budget that has no override.\n\nRequires the `AccessProfiles.Update` permission.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "ID of the user whose access-profile budget override is being removed", "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "description": "ID of the access profile assigned to the user", "schema": { "type": "integer" } }, { "name": "budget_id", "in": "path", "required": true, "description": "ID of a budget on the user's copy of the access profile", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Budget override removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideResponse" } } } }, "404": { "description": "User access profile or budget not found, or the profile is outside the caller's access scope" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/access-profiles/{profile_id}/virtual-keys": { "post": { "operationId": "addUserAccessProfileVirtualKey", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Add an extra virtual key under a user's access profile", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual key created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "virtual_key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string", "description": "The generated virtual key secret. Shown only once on creation." } } } } } } } }, "404": { "description": "User access profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/access-profiles/virtual-keys/{vk_id}": { "delete": { "operationId": "deleteUserAccessProfileVirtualKey", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete a virtual key from a user's access profile", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "vk_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual key deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Virtual key not found for this user" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/virtual-keys/{vk_id}/users": { "get": { "operationId": "listVirtualKeyUsersLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/virtual-keys/{vk_id}/users` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List users attached to a virtual key (deprecated path)", "tags": [ "Virtual Keys", "Users" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Attached users", "content": { "application/json": { "schema": { "type": "object", "required": [ "users", "count" ], "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "count": { "type": "integer" } } } } } } }, "x-bifrost-successor": "/api/governance/virtual-keys/{vk_id}/users", "x-bifrost-removal": "following-major-release", "deprecated": true }, "post": { "operationId": "attachVirtualKeyUsersLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/virtual-keys/{vk_id}/users` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Attach users to a virtual key (deprecated path)", "tags": [ "Virtual Keys", "Users" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_ids" ], "properties": { "user_ids": { "type": "array", "items": { "type": "string" } }, "preserve_usage": { "type": "boolean", "default": false } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Users attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } }, "x-bifrost-successor": "/api/governance/virtual-keys/{vk_id}/users", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/virtual-keys/{vk_id}/users/{user_id}": { "delete": { "operationId": "detachVirtualKeyUserLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/virtual-keys/{vk_id}/users/{user_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach a user from a virtual key (deprecated path)", "tags": [ "Virtual Keys", "Users" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "User detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } }, "x-bifrost-successor": "/api/governance/virtual-keys/{vk_id}/users/{user_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/teams/{team_id}/customers": { "get": { "operationId": "listTeamCustomersLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}/customers` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List customers attached to a team (deprecated path)", "tags": [ "Teams", "Customers" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Attached customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}/customers", "x-bifrost-removal": "following-major-release", "deprecated": true }, "post": { "operationId": "attachTeamCustomerLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}/customers` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Attach a customer to a team (deprecated path)", "tags": [ "Teams", "Customers" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customer attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}/customers", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/teams/{team_id}/customers/{customer_id}": { "delete": { "operationId": "detachTeamCustomerLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}/customers/{customer_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach a customer from a team (deprecated path)", "tags": [ "Teams", "Customers" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Customer detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}/customers/{customer_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/customers/{customer_id}/teams": { "get": { "operationId": "listCustomerTeamsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/customers/{customer_id}/teams` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List teams attached to a customer (deprecated path)", "tags": [ "Customers", "Teams" ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Attached teams", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } }, "x-bifrost-successor": "/api/governance/customers/{customer_id}/teams", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/roles": { "get": { "operationId": "listRolesLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/roles` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List roles (deprecated path)", "description": "Returns all roles visible to the caller, scoped by data access control.", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "description": "Lowercase letters, digits, `_`, `.`. Must start with a letter. Unique.", "maxLength": 255 }, "description": { "type": "string" }, "is_system_role": { "type": "boolean", "description": "True for built-in roles. System roles cannot be deleted." }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" }, "created_by_user_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/roles", "x-bifrost-removal": "following-major-release", "deprecated": true }, "post": { "operationId": "createRoleLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/roles` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create role (deprecated path)", "description": "Creates a custom role with the specified data access control scope.\nIf `dac` is omitted, defaults to `all-data`.\n", "tags": [ "RBAC" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Must match `^[a-z][a-z0-9_.]*$`. Max 255 characters. Unique.\n", "maxLength": 255 }, "description": { "type": "string" }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Defaults to `all-data` when omitted." } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role created", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "description": "Lowercase letters, digits, `_`, `.`. Must start with a letter. Unique.", "maxLength": 255 }, "description": { "type": "string" }, "is_system_role": { "type": "boolean", "description": "True for built-in roles. System roles cannot be deleted." }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" }, "created_by_user_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/roles", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/roles/{role_id}": { "get": { "operationId": "getRoleLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/roles/{role_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get role by ID (deprecated path)", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "description": "Lowercase letters, digits, `_`, `.`. Must start with a letter. Unique.", "maxLength": 255 }, "description": { "type": "string" }, "is_system_role": { "type": "boolean", "description": "True for built-in roles. System roles cannot be deleted." }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" }, "created_by_user_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/roles/{role_id}", "x-bifrost-removal": "following-major-release", "deprecated": true }, "put": { "operationId": "updateRoleLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/roles/{role_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update role (deprecated path)", "description": "Partial update. Omitted fields preserve the current value.\nNotable: omitting `dac` preserves the current scope (does not default to `all-data`).\n", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update. Omitted fields preserve the current value.\n- `description` is a nullable string: omitting it preserves the existing description; sending an empty string clears it.\n- `dac` defaults to the existing value when omitted, preventing accidental scope escalation.\n", "properties": { "name": { "type": "string", "description": "If supplied (and different from current), must match the role-name regex.", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "description": "Lowercase letters, digits, `_`, `.`. Must start with a letter. Unique.", "maxLength": 255 }, "description": { "type": "string" }, "is_system_role": { "type": "boolean", "description": "True for built-in roles. System roles cannot be deleted." }, "dac": { "type": "string", "enum": [ "own-data", "team-data", "all-data" ], "description": "Data access scope. Determines which rows members of the role can see.\n- `own-data` - Only rows the member personally owns.\n- `team-data` - Own rows plus rows owned by any team they belong to.\n- `all-data` - No row filtering.\n" }, "created_by_user_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/roles/{role_id}", "x-bifrost-removal": "following-major-release", "deprecated": true }, "delete": { "operationId": "deleteRoleLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/roles/{role_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete role (deprecated path)", "description": "Deletes a custom role. Built-in system roles cannot be deleted and return 403.\n", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "403": { "description": "Cannot delete system role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "cannot delete system role" } } } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/roles/{role_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/roles/{role_id}/permissions": { "get": { "operationId": "getRolePermissionsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/roles/{role_id}/permissions` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List permissions assigned to a role (deprecated path)", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "resource": { "type": "string" }, "operation": { "type": "string" } } } } } } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/roles/{role_id}/permissions", "x-bifrost-removal": "following-major-release", "deprecated": true }, "put": { "operationId": "updateRolePermissionsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/roles/{role_id}/permissions` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Replace the permission set on a role (deprecated path)", "description": "Replaces the permission set assigned to the role.\nSend the complete list of permission IDs that should be active for the role.\n", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "permission_ids" ], "properties": { "permission_ids": { "type": "array", "items": { "type": "integer", "format": "uint" } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Permissions updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/roles/{role_id}/permissions", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/resources": { "get": { "operationId": "listResourcesLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/resources` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List RBAC resources (deprecated path)", "description": "Returns the set of resource names that permissions can target.", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/resources", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/operations": { "get": { "operationId": "listOperationsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/operations` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List RBAC operations (deprecated path)", "description": "Returns the set of operation names that permissions can grant.", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/operations", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/permissions": { "get": { "operationId": "listPermissionsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/rbac/permissions` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List all RBAC permissions (deprecated path)", "description": "Returns every (resource, operation) pair that can be granted to a role.", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "resource": { "type": "string" }, "operation": { "type": "string" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/rbac/permissions", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users": { "get": { "operationId": "listUsersLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List users (deprecated path)", "description": "Returns a paginated list of users with optional search.", "tags": [ "Users" ], "parameters": [ { "name": "page", "in": "query", "description": "Legacy 1-based page number", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of users per page (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "search", "in": "query", "description": "Search by name or email", "schema": { "type": "string" } }, { "name": "team_id", "in": "query", "description": "Filter by team ID", "schema": { "type": "string" } }, { "name": "business_unit_id", "in": "query", "description": "Filter by business unit ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Legacy paginated response", "content": { "application/json": { "schema": { "type": "object", "required": [ "users", "total", "page", "limit", "total_pages", "has_more" ], "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users", "x-bifrost-removal": "following-major-release", "deprecated": true }, "post": { "operationId": "createUserLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create user (deprecated path)", "description": "Manually creates a new user in the organization.", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$", "description": "User's email address (must be unique)" }, "role_id": { "type": "integer", "description": "Optional RBAC role ID to assign" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "User created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "User with this email already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}": { "get": { "operationId": "getUserLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get user (deprecated path)", "description": "Returns a single Enterprise user.", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}", "x-bifrost-removal": "following-major-release", "deprecated": true }, "delete": { "operationId": "deleteUserLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete user (deprecated path)", "description": "Permanently removes a user from the organization. This cascades to delete the user's governance settings (budget/rate limits), team memberships, access profiles, and OIDC sessions. Cannot delete yourself.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request (e.g. cannot delete yourself)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/me/permissions": { "get": { "operationId": "getCurrentUserPermissionsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/me/permissions` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get current user permissions (deprecated path)", "description": "Returns the RBAC permissions for the authenticated user. When SCIM is not enabled, returns full permissions for all resources. Otherwise returns the permissions associated with the user's assigned role.\n", "tags": [ "Users" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "object", "description": "Map of resource names to their permitted operations. When SCIM is disabled, returns full permissions for all resources.\n", "additionalProperties": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized (user not authenticated)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/me/permissions", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}/role": { "put": { "operationId": "assignUserRoleLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/role` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Assign role to user (deprecated path)", "description": "Assigns an RBAC role to a user. This also auto-assigns the default access profile for the new role and reloads the RBAC permission cache.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "integer", "description": "ID of the RBAC role to assign" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role assigned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User or role not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/role", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}/teams": { "get": { "operationId": "getUserTeamsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/teams` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get user's teams (deprecated path)", "description": "Returns the list of teams a user belongs to, including the membership source.", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "source": { "type": "string", "description": "How the user was added to this team (e.g. \"manual\", \"scim_sync\")" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/teams", "x-bifrost-removal": "following-major-release", "deprecated": true }, "put": { "operationId": "updateUserTeamsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/teams` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update user's team assignments (deprecated path)", "description": "Replaces the user's manual team assignments. Synced team memberships (from SCIM providers) are preserved and cannot be removed via this endpoint.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "team_ids" ], "properties": { "team_ids": { "type": "array", "items": { "type": "string" }, "description": "List of team IDs to assign (replaces existing manual assignments; synced memberships are preserved)" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Teams updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request (e.g. team not found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/teams", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/email/{email}/virtual-keys": { "get": { "operationId": "getUserVirtualKeysByEmailLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/email/{email}/virtual-keys` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get user's virtual keys by email (deprecated path)", "description": "**Enterprise only.**\nReturns all virtual keys associated with a user, looked up by email address. Returns an empty `virtual_keys` array when the user exists but has no virtual keys assigned. Intended for MDM and credential-helper integrations that need to resolve a user's keys without knowing their internal ID.\n", "tags": [ "Users" ], "parameters": [ { "name": "email", "in": "path", "required": true, "description": "URL-encoded email address of the user", "schema": { "type": "string", "format": "email" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Internal ID of the resolved user" }, "email": { "type": "string", "format": "email", "description": "Email address of the resolved user" }, "virtual_keys": { "type": "array", "description": "Virtual keys assigned to this user", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Virtual key ID" }, "name": { "type": "string", "description": "Virtual key display name" }, "value": { "type": "string", "description": "Virtual key token value" }, "is_active": { "type": "boolean", "nullable": true, "description": "Whether the virtual key is currently active" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/email/{email}/virtual-keys", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/email/{email}": { "get": { "operationId": "getUserByEmailLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/email/{email}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get user by email (deprecated path)", "description": "Returns a single Enterprise user resolved by URL-encoded email address.", "tags": [ "Users" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role_id": { "type": "integer", "nullable": true, "description": "ID of the assigned RBAC role" }, "role": { "type": "object", "nullable": true, "description": "RBAC role details", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_system_role": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "description": "Teams the user belongs to.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "business_unit_id": { "type": "string", "nullable": true, "description": "Business unit ID associated with this team (if any)" }, "business_unit_name": { "type": "string", "nullable": true, "description": "Business unit name associated with this team (if any)" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Active or fallback user access profile, if assigned.", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/email/{email}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/teams": { "get": { "operationId": "listTeamsLegacy", "summary": "List teams (deprecated path)", "description": "Returns a list of all teams.", "tags": [ "Governance" ], "parameters": [ { "name": "page", "in": "query", "description": "Legacy 1-based page number", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of teams per page (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "search", "in": "query", "description": "Search by team name", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Set to `business_unit` to include business-unit associations", "schema": { "type": "string", "enum": [ "business_unit" ] } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Legacy paginated response", "content": { "application/json": { "schema": { "type": "object", "required": [ "teams", "total", "page", "limit" ], "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/teams", "x-bifrost-removal": "following-major-release", "deprecated": true, "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams` instead.\n\n" } }, "post": { "operationId": "createTeamLegacy", "summary": "Create team (deprecated path)", "description": "Creates a new team.", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Team created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/teams", "x-bifrost-removal": "following-major-release", "deprecated": true, "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams` instead.\n\n" } } }, "/api/teams/{team_id}": { "get": { "operationId": "getTeamLegacy", "summary": "Get team (deprecated path)", "description": "Returns a specific team by ID.", "tags": [ "Governance" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } }, { "name": "from_memory", "in": "query", "description": "If true, returns team from in-memory cache instead of database", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" } } } } } }, "404": { "description": "Team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}", "x-bifrost-removal": "following-major-release", "deprecated": true, "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}` instead.\n\n" } }, "put": { "operationId": "updateTeamLegacy", "summary": "Update team (deprecated path)", "description": "Updates an existing team.", "tags": [ "Governance" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Team updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}", "x-bifrost-removal": "following-major-release", "deprecated": true, "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}` instead.\n\n" } }, "delete": { "operationId": "deleteTeamLegacy", "summary": "Delete team (deprecated path)", "description": "Deletes a team.", "tags": [ "Governance" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Team deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}", "x-bifrost-removal": "following-major-release", "deprecated": true, "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}` instead.\n\n" } } }, "/api/teams/{team_id}/members": { "get": { "operationId": "getTeamMembersLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}/members` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List team members (deprecated path)", "description": "Returns all members of a team with their user details and membership source.", "tags": [ "Teams" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "user_name": { "type": "string" }, "user_email": { "type": "string" }, "source": { "type": "string", "description": "How the member was added (e.g. \"manual\", \"scim_sync\")" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Team not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}/members", "x-bifrost-removal": "following-major-release", "deprecated": true }, "post": { "operationId": "addTeamMemberLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}/members` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Add team member (deprecated path)", "description": "Adds a user to a team. Both the team and user must exist.", "tags": [ "Teams" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "ID of the user to add to the team" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Member added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Team or user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "409": { "description": "User is already a member of this team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}/members", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/teams/{team_id}/members/{user_id}": { "delete": { "operationId": "removeTeamMemberLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams/{team_id}/members/{user_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Remove team member (deprecated path)", "description": "Removes a user from a team.", "tags": [ "Teams" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "description": "User ID to remove", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Member removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Membership not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/teams/{team_id}/members/{user_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles": { "get": { "operationId": "listAccessProfilesLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List access profiles (deprecated path)", "description": "Returns access profiles visible to the caller.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Comma-separated list of tags to filter on.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" }, "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles", "x-bifrost-removal": "following-major-release", "deprecated": true }, "post": { "operationId": "createAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create access profile (deprecated path)", "description": "Creates a new access profile template. The profile is inactive until attached to a role.\nNo size limits are enforced on create; the limits apply on update.\n", "tags": [ "Access Profiles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Profile created", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "A profile with the same name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}": { "get": { "operationId": "getAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get access profile by ID (deprecated path)", "description": "Returns the profile plus its role attachments and the count of users holding a copy.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Returned by GET /api/access-profiles/{id}. Includes role attachments and the count of users holding a copy.", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "access_profile_id": { "type": "integer", "format": "uint" }, "role_id": { "type": "integer", "format": "uint" }, "role_name": { "type": "string" }, "is_default": { "type": "boolean" } } } }, "user_count": { "type": "integer" } } } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}", "x-bifrost-removal": "following-major-release", "deprecated": true }, "put": { "operationId": "updateAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update access profile (deprecated path)", "description": "Partial update. Omitted fields preserve the current value.\n`rate_limit: null` explicitly clears the existing rate limit.\nSize limits enforced: max 100 provider_configs, max 100 budgets, max 50 tags.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update. Omitted fields preserve the current value.\n`rate_limit: null` explicitly clears the existing rate limit; omitting the field preserves it.\nUpdate enforces size limits not enforced on create: max 100 provider_configs, max 100 budgets, max 50 tags.\n", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "nullable": true, "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } ] }, "calendar_aligned": { "type": "boolean", "nullable": true }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Profile not found" }, "409": { "description": "A profile with the same name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}", "x-bifrost-removal": "following-major-release", "deprecated": true }, "delete": { "operationId": "deleteAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete access profile (deprecated path)", "description": "Blocked with 409 if any users still hold copies. Detach role attachments or remove user assignments first.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Profile not found" }, "409": { "description": "Profile has active user copies; detach users first." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/activate": { "put": { "operationId": "activateAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/activate` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Activate access profile (deprecated path)", "description": "Sets the profile active. Idempotent.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile is active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/activate", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/deactivate": { "put": { "operationId": "deactivateAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/deactivate` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Deactivate access profile (deprecated path)", "description": "Sets the profile inactive. Idempotent. User copies are preserved; the profile is hidden from selection menus.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile is inactive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/deactivate", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/clone": { "post": { "operationId": "cloneAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/clone` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Clone an access profile (deprecated path)", "description": "Creates a fresh copy of the profile under a new name. The clone has no role attachments or user copies.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Cloned profile created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profile": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "provider_configs": { "type": "array", "items": { "type": "object", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "format": "uint", "readOnly": true }, "provider_name": { "type": "string", "description": "Provider identifier (`anthropic`, `openai`, `bedrock`, ...)." }, "all_models_allowed": { "type": "boolean", "description": "If true, every model from this provider is allowed." }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Explicit model list. Empty array denies all models from the provider." }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } } } } }, "budgets": { "type": "array", "items": { "type": "object", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "readOnly": true }, "max_limit": { "type": "number", "description": "Cap in dollars (or tokens, depending on configured pricing)." }, "reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Q", "1Y" ], "description": "Reset duration for a budget." }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1." } }, "additionalProperties": false }, "scope": { "type": "string", "description": "Set server-side. `total` for global budgets, `provider:` for per-provider budgets." }, "current_usage": { "type": "number", "readOnly": true }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "token_max_limit": { "type": "number", "nullable": true }, "token_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "request_max_limit": { "type": "number", "nullable": true }, "request_reset_duration": { "type": "string", "enum": [ "1h", "1d", "1w", "1M", "1Y" ], "description": "Reset duration for a rate limit." }, "token_current_usage": { "type": "number", "readOnly": true }, "request_current_usage": { "type": "number", "readOnly": true } } }, "calendar_aligned": { "type": "boolean" }, "mcp_tool_groups": { "type": "array", "items": { "type": "object", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id", "tool_name", "action" ], "properties": { "mcp_client_id": { "type": "string" }, "tool_name": { "type": "string" }, "action": { "type": "string", "enum": [ "include", "exclude" ] } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Source profile not found" }, "409": { "description": "A profile with the same name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/clone", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/propagate": { "post": { "operationId": "propagateAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/propagate` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Propagate template changes to user copies (deprecated path)", "description": "Pushes selected fields from the template to every user that holds a copy.\nUse `dry_run: true` to preview the impact. By default, accumulated usage is preserved.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fields" ], "properties": { "dry_run": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "provider_configs", "budgets", "rate_limit", "mcp_tool_groups", "mcp_servers", "mcp_tool_overrides" ] }, "minItems": 1 }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Empty or omitted = all users with a copy of this profile." }, "group_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by SCIM group or team IDs." }, "reset_usage": { "type": "boolean", "description": "If true, zero out budget and rate-limit usage on cloned rows. Default false (preserves usage)." } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Propagation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected_users": { "type": "integer" }, "failed_users": { "type": "integer" }, "skipped_users": { "type": "integer" }, "user_ids": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "array", "items": { "type": "string" } }, "applied": { "type": "boolean", "description": "False on dry run, true when changes were persisted." }, "vk_sync_errors": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/propagate", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/roles": { "post": { "operationId": "attachAccessProfileRolesLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/roles` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Attach roles to access profile (deprecated path)", "description": "Attaches one or more roles. Setting `is_default: true` makes the profile the role's default\nfor new users. `apply_to_existing: true` provisions the profile to users already in the role.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role_ids" ], "properties": { "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint" }, "minItems": 1 }, "is_default": { "type": "boolean" }, "apply_to_existing": { "type": "boolean" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Roles attached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "users_applied": { "type": "integer" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/roles", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/roles/{role_id}": { "delete": { "operationId": "detachAccessProfileRoleLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/roles/{role_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach role from access profile (deprecated path)", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Role detached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Role attachment not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/roles/{role_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/versions": { "get": { "operationId": "listAccessProfileVersionsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/versions` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List version snapshots for an access profile (deprecated path)", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "access_profile_id": { "type": "integer" }, "version": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "snapshot": { "type": "string", "description": "JSON snapshot of the profile at this version." }, "changed_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/versions", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/versions/{version}": { "get": { "operationId": "getAccessProfileVersionLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/versions/{version}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get a single version snapshot (deprecated path)", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "integer" }, "access_profile_id": { "type": "integer" }, "version": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "snapshot": { "type": "string", "description": "JSON snapshot of the profile at this version." }, "changed_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "Version not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/versions/{version}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/{profile_id}/audit-logs": { "get": { "operationId": "getAccessProfileAuditLogsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/{profile_id}/audit-logs` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List audit log entries for a single profile (deprecated path)", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "description": "One of create, update, delete, propagate, attach_role, detach_role, clone, activate, deactivate.", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "access_profile_id": { "type": "integer", "nullable": true }, "user_id": { "type": "string", "nullable": true }, "actor": { "type": "string" }, "action": { "type": "string" }, "previous_values": { "type": "string", "nullable": true }, "new_values": { "type": "string", "nullable": true }, "metadata": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "total_count": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/{profile_id}/audit-logs", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/access-profiles/audit-logs": { "get": { "operationId": "getAllAccessProfileAuditLogsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/access-profiles/audit-logs` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List workspace-wide audit log entries (deprecated path)", "tags": [ "Access Profiles" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "access_profile_id": { "type": "integer", "nullable": true }, "user_id": { "type": "string", "nullable": true }, "actor": { "type": "string" }, "action": { "type": "string" }, "previous_values": { "type": "string", "nullable": true }, "new_values": { "type": "string", "nullable": true }, "metadata": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "total_count": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/access-profiles/audit-logs", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}/access-profiles": { "get": { "operationId": "getUserAccessProfilesLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/access-profiles` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List access profiles held by a user (deprecated path)", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_profiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "parent_profile_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "virtual_key_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map of virtual key ID to masked secret value." } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/access-profiles", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}/virtual-keys": { "get": { "operationId": "listUserVirtualKeysLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/virtual-keys` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List virtual keys available to a user (deprecated path)", "tags": [ "Users", "Virtual Keys" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "User virtual keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "virtual_keys": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/virtual-keys", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override": { "put": { "operationId": "updateUserAccessProfileBudgetOverrideLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Set a user's access-profile budget override (deprecated path)", "description": "Sets or replaces the spending override on one budget of a single user's copy of an access profile.\nThe override is additive — while it is active the budget is enforced against\n`max_limit + override_amount` — and it leaves the budget's base limit, current usage, and reset\nschedule untouched. Only this user is affected; the access profile template and every other user\nassigned to it keep their original limits.\n\nUse `mode: cycles` with a `cycles` count to grant extra spend for a finite number of reset windows\n(the current window counts as the first), or `mode: forever` to keep the override until it is deleted.\nA finite grant is anchored to the profile's reset window — calendar-aligned profiles anchor at the\ncalendar period start — so every node in a cluster derives the same number of remaining cycles.\nThe change is propagated cluster-wide and survives access-profile cloning and propagation.\n\nRequires the `AccessProfiles.Update` permission. `budget_id` must be a budget on the user's own copy\nof the profile, not on the shared template.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "ID of the user whose access-profile budget is being overridden", "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "description": "ID of the access profile assigned to the user", "schema": { "type": "integer" } }, { "name": "budget_id", "in": "path", "required": true, "description": "ID of a budget on the user's copy of the access profile", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Budget override applied successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User access profile or budget not found, or the profile is outside the caller's access scope" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override", "x-bifrost-removal": "following-major-release", "deprecated": true }, "delete": { "operationId": "deleteUserAccessProfileBudgetOverrideLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Remove a user's access-profile budget override (deprecated path)", "description": "Removes any active override from the user's budget, so it is enforced against its base `max_limit`\nagain. The budget's current usage and reset schedule are unchanged, and the removal is permanent — a\ncleared grant cannot be re-derived. Safe to call on a budget that has no override.\n\nRequires the `AccessProfiles.Update` permission.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "ID of the user whose access-profile budget override is being removed", "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "description": "ID of the access profile assigned to the user", "schema": { "type": "integer" } }, { "name": "budget_id", "in": "path", "required": true, "description": "ID of a budget on the user's copy of the access profile", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Budget override removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetOverrideResponse" } } } }, "404": { "description": "User access profile or budget not found, or the profile is outside the caller's access scope" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}/access-profiles/{profile_id}": { "delete": { "operationId": "detachUserAccessProfileLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/access-profiles/{profile_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Detach a user's access profile (deprecated path)", "description": "Removes the profile from the user and deletes every virtual key it produced. Fails closed if a virtual key cannot be deleted.", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Profile detached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "deleted_vk_names": { "type": "array", "items": { "type": "string" } }, "deleted_vk_count": { "type": "integer" } } } } } }, "404": { "description": "User access profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/access-profiles/{profile_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}/access-profiles/{profile_id}/virtual-keys": { "post": { "operationId": "addUserAccessProfileVirtualKeyLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/access-profiles/{profile_id}/virtual-keys` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Add an extra virtual key under a user's access profile (deprecated path)", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual key created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "virtual_key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string", "description": "The generated virtual key secret. Shown only once on creation." } } } } } } } }, "404": { "description": "User access profile not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/access-profiles/{profile_id}/virtual-keys", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/users/{user_id}/access-profiles/virtual-keys/{vk_id}": { "delete": { "operationId": "deleteUserAccessProfileVirtualKeyLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/users/{user_id}/access-profiles/virtual-keys/{vk_id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete a virtual key from a user's access profile (deprecated path)", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "vk_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual key deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Virtual key not found for this user" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/access-profiles/virtual-keys/{vk_id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/governance/audit-logs": { "get": { "operationId": "getAuditLogs", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List audit logs", "description": "Retrieves CADF-compliant audit log events with filtering, search, and\npagination via query parameters. Most filter dimensions accept either a\nsingle value (singular parameter, e.g. `action`) or a JSON-encoded array\nof values (plural parameter, e.g. `actions`); when both are supplied the\nplural array takes precedence.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number for offset-based pagination (default 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Number of events to return per page (default 100, max 1000).", "schema": { "type": "integer", "default": 100, "maximum": 1000 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor for cursor-based pagination (from `next_cursor`).", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search across audit event fields.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Filter by a single CADF action.", "schema": { "$ref": "#/components/schemas/AuditAction" } }, { "name": "actions", "in": "query", "description": "JSON array of CADF actions to filter by (OR match).", "schema": { "type": "string" }, "example": "[\"create\",\"update\"]" }, { "name": "outcome", "in": "query", "description": "Filter by a single outcome.", "schema": { "$ref": "#/components/schemas/AuditOutcome" } }, { "name": "outcomes", "in": "query", "description": "JSON array of outcomes to filter by (OR match).", "schema": { "type": "string" }, "example": "[\"success\",\"failure\"]" }, { "name": "event_type", "in": "query", "description": "Filter by a single event type.", "schema": { "$ref": "#/components/schemas/AuditEventType" } }, { "name": "event_types", "in": "query", "description": "JSON array of event types to filter by (OR match).", "schema": { "type": "string" }, "example": "[\"activity\",\"control\"]" }, { "name": "initiator_id", "in": "query", "description": "Filter by a single initiator ID.", "schema": { "type": "string" } }, { "name": "initiator_ids", "in": "query", "description": "JSON array of initiator IDs to filter by (OR match).", "schema": { "type": "string" } }, { "name": "initiator_type", "in": "query", "description": "Filter by a single initiator resource type.", "schema": { "$ref": "#/components/schemas/AuditResourceType" } }, { "name": "initiator_types", "in": "query", "description": "JSON array of initiator resource types to filter by (OR match).", "schema": { "type": "string" } }, { "name": "target_id", "in": "query", "description": "Filter by a single target ID.", "schema": { "type": "string" } }, { "name": "target_ids", "in": "query", "description": "JSON array of target IDs to filter by (OR match).", "schema": { "type": "string" } }, { "name": "target_type", "in": "query", "description": "Filter by a single target resource type.", "schema": { "$ref": "#/components/schemas/AuditResourceType" } }, { "name": "target_types", "in": "query", "description": "JSON array of target resource types to filter by (OR match).", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Filter events at or after this time (RFC3339 or `YYYY-MM-DD`).", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "Filter events at or before this time (RFC3339 or `YYYY-MM-DD`; a date is treated as end-of-day).", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Relative time window that overrides `start_date`/`end_date` when set (e.g. `24h`, `7d`).", "schema": { "type": "string" } }, { "name": "request_method", "in": "query", "description": "Filter by a single HTTP request method.", "schema": { "type": "string" } }, { "name": "request_methods", "in": "query", "description": "JSON array of HTTP request methods to filter by (OR match).", "schema": { "type": "string" } }, { "name": "request_path", "in": "query", "description": "Filter by a single request path prefix.", "schema": { "type": "string" } }, { "name": "request_paths", "in": "query", "description": "JSON array of request path prefixes to filter by (OR match).", "schema": { "type": "string" } }, { "name": "request_ip", "in": "query", "description": "Filter by a single client IP address.", "schema": { "type": "string" } }, { "name": "request_ips", "in": "query", "description": "JSON array of client IP addresses to filter by (OR match).", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "JSON array of tags to filter by (any match).", "schema": { "type": "string" }, "example": "[\"security\",\"auth\"]" }, { "name": "sort_by", "in": "query", "description": "Field to sort by (default `event_time`).", "schema": { "type": "string", "default": "event_time" } }, { "name": "sort_order", "in": "query", "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogsResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/audit-logs/filterdata": { "get": { "operationId": "getAuditLogsFilterData", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get audit log filter data", "description": "Returns the distinct values available for each audit log filter dimension,\nused to populate filter dropdowns in the dashboard.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "dimensions", "in": "query", "description": "Comma-separated list of dimensions to return. When omitted, all\ndimensions are returned. Unknown dimensions are ignored.\n", "schema": { "type": "string", "example": "actions,outcomes,initiators" } }, { "name": "q", "in": "query", "description": "Optional case-insensitive substring filter applied to dimension values.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditFilterDataResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/audit-logs/export": { "get": { "operationId": "exportAuditLogs", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Export audit logs", "description": "Streams audit log events matching the supplied filters as a downloadable\nfile. Accepts the same filter query parameters as `GET /api/audit-logs`.\nThe response is returned as an attachment with a generated filename.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "format", "in": "query", "description": "Export format. Defaults to `json` when omitted or unrecognized.\n- `json`: a JSON array of events\n- `jsonl`: JSON Lines, one event per line\n- `syslog`: RFC 5424 syslog format\n", "schema": { "type": "string", "enum": [ "json", "jsonl", "syslog" ], "default": "json" } }, { "name": "search", "in": "query", "description": "Free-text search across audit event fields.", "schema": { "type": "string" } }, { "name": "actions", "in": "query", "description": "JSON array of CADF actions to filter by (OR match).", "schema": { "type": "string" } }, { "name": "outcomes", "in": "query", "description": "JSON array of outcomes to filter by (OR match).", "schema": { "type": "string" } }, { "name": "event_types", "in": "query", "description": "JSON array of event types to filter by (OR match).", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Filter events at or after this time (RFC3339 or `YYYY-MM-DD`).", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "Filter events at or before this time (RFC3339 or `YYYY-MM-DD`).", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Relative time window that overrides `start_date`/`end_date` when set (e.g. `24h`, `7d`).", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "A streamed export of the matching audit logs.", "content": { "application/json": { "schema": { "type": "string" } }, "application/x-ndjson": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/audit-logs/{id}": { "get": { "operationId": "getAuditLogById", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get audit log by ID", "description": "Retrieves a single audit log event by its unique ID.", "tags": [ "Audit Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the audit log event.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/audit-logs/{id}/verify": { "get": { "operationId": "verifyAuditLogSignature", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Verify audit log signature", "description": "Recomputes the HMAC-SHA256 signature for a single audit log event and\ncompares it (in constant time) against the stored signature to detect\ntampering.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the audit log event to verify.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditVerifyResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/audit-logs": { "get": { "operationId": "getAuditLogsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/audit-logs` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List audit logs (deprecated path)", "description": "Retrieves CADF-compliant audit log events with filtering, search, and\npagination via query parameters. Most filter dimensions accept either a\nsingle value (singular parameter, e.g. `action`) or a JSON-encoded array\nof values (plural parameter, e.g. `actions`); when both are supplied the\nplural array takes precedence.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number for offset-based pagination (default 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Number of events to return per page (default 100, max 1000).", "schema": { "type": "integer", "default": 100, "maximum": 1000 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor for cursor-based pagination (from `next_cursor`).", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search across audit event fields.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Filter by a single CADF action.", "schema": { "$ref": "#/components/schemas/AuditAction" } }, { "name": "actions", "in": "query", "description": "JSON array of CADF actions to filter by (OR match).", "schema": { "type": "string" }, "example": "[\"create\",\"update\"]" }, { "name": "outcome", "in": "query", "description": "Filter by a single outcome.", "schema": { "$ref": "#/components/schemas/AuditOutcome" } }, { "name": "outcomes", "in": "query", "description": "JSON array of outcomes to filter by (OR match).", "schema": { "type": "string" }, "example": "[\"success\",\"failure\"]" }, { "name": "event_type", "in": "query", "description": "Filter by a single event type.", "schema": { "$ref": "#/components/schemas/AuditEventType" } }, { "name": "event_types", "in": "query", "description": "JSON array of event types to filter by (OR match).", "schema": { "type": "string" }, "example": "[\"activity\",\"control\"]" }, { "name": "initiator_id", "in": "query", "description": "Filter by a single initiator ID.", "schema": { "type": "string" } }, { "name": "initiator_ids", "in": "query", "description": "JSON array of initiator IDs to filter by (OR match).", "schema": { "type": "string" } }, { "name": "initiator_type", "in": "query", "description": "Filter by a single initiator resource type.", "schema": { "$ref": "#/components/schemas/AuditResourceType" } }, { "name": "initiator_types", "in": "query", "description": "JSON array of initiator resource types to filter by (OR match).", "schema": { "type": "string" } }, { "name": "target_id", "in": "query", "description": "Filter by a single target ID.", "schema": { "type": "string" } }, { "name": "target_ids", "in": "query", "description": "JSON array of target IDs to filter by (OR match).", "schema": { "type": "string" } }, { "name": "target_type", "in": "query", "description": "Filter by a single target resource type.", "schema": { "$ref": "#/components/schemas/AuditResourceType" } }, { "name": "target_types", "in": "query", "description": "JSON array of target resource types to filter by (OR match).", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Filter events at or after this time (RFC3339 or `YYYY-MM-DD`).", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "Filter events at or before this time (RFC3339 or `YYYY-MM-DD`; a date is treated as end-of-day).", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Relative time window that overrides `start_date`/`end_date` when set (e.g. `24h`, `7d`).", "schema": { "type": "string" } }, { "name": "request_method", "in": "query", "description": "Filter by a single HTTP request method.", "schema": { "type": "string" } }, { "name": "request_methods", "in": "query", "description": "JSON array of HTTP request methods to filter by (OR match).", "schema": { "type": "string" } }, { "name": "request_path", "in": "query", "description": "Filter by a single request path prefix.", "schema": { "type": "string" } }, { "name": "request_paths", "in": "query", "description": "JSON array of request path prefixes to filter by (OR match).", "schema": { "type": "string" } }, { "name": "request_ip", "in": "query", "description": "Filter by a single client IP address.", "schema": { "type": "string" } }, { "name": "request_ips", "in": "query", "description": "JSON array of client IP addresses to filter by (OR match).", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "JSON array of tags to filter by (any match).", "schema": { "type": "string" }, "example": "[\"security\",\"auth\"]" }, { "name": "sort_by", "in": "query", "description": "Field to sort by (default `event_time`).", "schema": { "type": "string", "default": "event_time" } }, { "name": "sort_order", "in": "query", "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogsResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/audit-logs", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/audit-logs/filterdata": { "get": { "operationId": "getAuditLogsFilterDataLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/audit-logs/filterdata` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get audit log filter data (deprecated path)", "description": "Returns the distinct values available for each audit log filter dimension,\nused to populate filter dropdowns in the dashboard.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "dimensions", "in": "query", "description": "Comma-separated list of dimensions to return. When omitted, all\ndimensions are returned. Unknown dimensions are ignored.\n", "schema": { "type": "string", "example": "actions,outcomes,initiators" } }, { "name": "q", "in": "query", "description": "Optional case-insensitive substring filter applied to dimension values.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditFilterDataResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/audit-logs/filterdata", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/audit-logs/export": { "get": { "operationId": "exportAuditLogsLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/audit-logs/export` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Export audit logs (deprecated path)", "description": "Streams audit log events matching the supplied filters as a downloadable\nfile. Accepts the same filter query parameters as `GET /api/audit-logs`.\nThe response is returned as an attachment with a generated filename.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "format", "in": "query", "description": "Export format. Defaults to `json` when omitted or unrecognized.\n- `json`: a JSON array of events\n- `jsonl`: JSON Lines, one event per line\n- `syslog`: RFC 5424 syslog format\n", "schema": { "type": "string", "enum": [ "json", "jsonl", "syslog" ], "default": "json" } }, { "name": "search", "in": "query", "description": "Free-text search across audit event fields.", "schema": { "type": "string" } }, { "name": "actions", "in": "query", "description": "JSON array of CADF actions to filter by (OR match).", "schema": { "type": "string" } }, { "name": "outcomes", "in": "query", "description": "JSON array of outcomes to filter by (OR match).", "schema": { "type": "string" } }, { "name": "event_types", "in": "query", "description": "JSON array of event types to filter by (OR match).", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Filter events at or after this time (RFC3339 or `YYYY-MM-DD`).", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "Filter events at or before this time (RFC3339 or `YYYY-MM-DD`).", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Relative time window that overrides `start_date`/`end_date` when set (e.g. `24h`, `7d`).", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "A streamed export of the matching audit logs.", "content": { "application/json": { "schema": { "type": "string" } }, "application/x-ndjson": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/audit-logs/export", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/audit-logs/{id}": { "get": { "operationId": "getAuditLogByIdLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/audit-logs/{id}` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get audit log by ID (deprecated path)", "description": "Retrieves a single audit log event by its unique ID.", "tags": [ "Audit Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the audit log event.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/audit-logs/{id}", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/audit-logs/{id}/verify": { "get": { "operationId": "verifyAuditLogSignatureLegacy", "x-mint": { "metadata": { "tag": "Removing soon" }, "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/audit-logs/{id}/verify` instead.\n\n\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Verify audit log signature (deprecated path)", "description": "Recomputes the HMAC-SHA256 signature for a single audit log event and\ncompares it (in constant time) against the stored signature to detect\ntampering.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the audit log event to verify.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditVerifyResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "x-bifrost-successor": "/api/governance/audit-logs/{id}/verify", "x-bifrost-removal": "following-major-release", "deprecated": true } }, "/api/mcp/tool-groups": { "get": { "operationId": "listMCPToolGroups", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List MCP Tool Groups", "description": "Returns tool groups visible to the caller. When all of `limit`, `offset`, and `search` are omitted, every group is returned in one response.\n", "tags": [ "MCP Tool Groups" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search by name.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_tool_groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "ID of a deployed MCP client." }, "tool_names": { "type": "array", "items": { "type": "string" }, "description": "Specific tools from this client to include in the group.\nAn empty or omitted array means \"all tools from this client\".\n" } } } }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "team_ids": { "type": "array", "items": { "type": "string" } }, "customer_ids": { "type": "array", "items": { "type": "string" } }, "user_ids": { "type": "array", "items": { "type": "string" } }, "provider_names": { "type": "array", "items": { "type": "string" } }, "api_key_ids": { "type": "array", "items": { "type": "integer", "format": "uint" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" }, "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createMCPToolGroup", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create MCP Tool Group", "description": "Creates a new tool group along with its attachments in a single transaction.\nValidates that every `mcp_client_id` points to a deployed MCP client and that every named\ntool exists on its server.\n", "tags": [ "MCP Tool Groups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "tools" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "enabled": { "type": "boolean", "description": "If omitted, the group is created with `enabled: false`.\nSend `true` explicitly to activate the group on creation.\n" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "ID of a deployed MCP client." }, "tool_names": { "type": "array", "items": { "type": "string" }, "description": "Specific tools from this client to include in the group.\nAn empty or omitted array means \"all tools from this client\".\n" } } } }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "team_ids": { "type": "array", "items": { "type": "string" } }, "customer_ids": { "type": "array", "items": { "type": "string" } }, "user_ids": { "type": "array", "items": { "type": "string" } }, "provider_names": { "type": "array", "items": { "type": "string" } }, "api_key_ids": { "type": "array", "items": { "type": "integer", "format": "uint" } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Group created", "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_tool_group": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "ID of a deployed MCP client." }, "tool_names": { "type": "array", "items": { "type": "string" }, "description": "Specific tools from this client to include in the group.\nAn empty or omitted array means \"all tools from this client\".\n" } } } }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "team_ids": { "type": "array", "items": { "type": "string" } }, "customer_ids": { "type": "array", "items": { "type": "string" } }, "user_ids": { "type": "array", "items": { "type": "string" } }, "provider_names": { "type": "array", "items": { "type": "string" } }, "api_key_ids": { "type": "array", "items": { "type": "integer", "format": "uint" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Validation failed (missing name, invalid MCP client IDs, or invalid tool names)." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/tool-groups/{id}": { "get": { "operationId": "getMCPToolGroup", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get MCP Tool Group by ID", "tags": [ "MCP Tool Groups" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_tool_group": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "ID of a deployed MCP client." }, "tool_names": { "type": "array", "items": { "type": "string" }, "description": "Specific tools from this client to include in the group.\nAn empty or omitted array means \"all tools from this client\".\n" } } } }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "team_ids": { "type": "array", "items": { "type": "string" } }, "customer_ids": { "type": "array", "items": { "type": "string" } }, "user_ids": { "type": "array", "items": { "type": "string" } }, "provider_names": { "type": "array", "items": { "type": "string" } }, "api_key_ids": { "type": "array", "items": { "type": "integer", "format": "uint" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "404": { "description": "MCP tool group not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateMCPToolGroup", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update MCP Tool Group", "description": "Partial update. Scalar fields preserve the current value when omitted.\nArray fields are replace-on-send: an empty array clears all attachments in that dimension.\n", "tags": [ "MCP Tool Groups" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial update.\n- Scalar fields (`name`, `description`, `enabled`) preserve the current value when omitted.\n- Array fields are replace-on-send: whatever you provide becomes the new full value. To clear an attachment dimension, send an empty array.\n", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean", "nullable": true }, "tools": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "ID of a deployed MCP client." }, "tool_names": { "type": "array", "items": { "type": "string" }, "description": "Specific tools from this client to include in the group.\nAn empty or omitted array means \"all tools from this client\".\n" } } } }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "team_ids": { "type": "array", "items": { "type": "string" } }, "customer_ids": { "type": "array", "items": { "type": "string" } }, "user_ids": { "type": "array", "items": { "type": "string" } }, "provider_names": { "type": "array", "items": { "type": "string" } }, "api_key_ids": { "type": "array", "items": { "type": "integer", "format": "uint" } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Group updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_tool_group": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "ID of a deployed MCP client." }, "tool_names": { "type": "array", "items": { "type": "string" }, "description": "Specific tools from this client to include in the group.\nAn empty or omitted array means \"all tools from this client\".\n" } } } }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "team_ids": { "type": "array", "items": { "type": "string" } }, "customer_ids": { "type": "array", "items": { "type": "string" } }, "user_ids": { "type": "array", "items": { "type": "string" } }, "provider_names": { "type": "array", "items": { "type": "string" } }, "api_key_ids": { "type": "array", "items": { "type": "integer", "format": "uint" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Validation failed." }, "404": { "description": "MCP tool group not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteMCPToolGroup", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete MCP Tool Group", "description": "Deletes the group; attachments are removed automatically.", "tags": [ "MCP Tool Groups" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Group deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "MCP tool group not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/circuit-breaker/policies": { "get": { "operationId": "listCircuitBreakerPolicies", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "List circuit breaker policies", "description": "Returns all circuit breaker policies defined in this workspace.", "tags": [ "Circuit Breaker" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "items": { "type": "object", "required": [ "name", "primary_provider", "primary_model", "fallback_provider", "fallback_model", "condition" ], "properties": { "name": { "type": "string", "description": "Unique name for this policy." }, "enabled": { "type": "boolean", "default": true, "description": "When `false`, the policy is registered but all hooks skip it." }, "primary_provider": { "type": "string", "description": "Provider to monitor (e.g. `azure`, `openai`)." }, "primary_model": { "type": "string", "description": "Model name as it appears in requests (e.g. `gpt-4o-ptu`)." }, "primary_key_ids": { "type": "array", "items": { "type": "string" }, "description": "API key UUIDs to track individually. Each key gets its own sub-circuit.\nThe main circuit opens only when all listed keys have tripped.\nLeave empty to use a single shared circuit for all keys serving this provider+model.\n" }, "fallback_provider": { "type": "string", "description": "Provider to route to when the circuit is open." }, "fallback_model": { "type": "string", "description": "Model to request from the fallback provider when the circuit is open." }, "condition": { "type": "object", "required": [ "signals" ], "properties": { "operator": { "type": "string", "enum": [ "OR", "AND" ], "default": "OR", "description": "How multiple signals are combined.\n`OR` (default): circuit opens when any signal matches.\n`AND`: circuit opens only when all signals match simultaneously.\n" }, "signals": { "type": "array", "minItems": 1, "description": "List of response signals to evaluate. At least one required.", "items": { "type": "object", "required": [ "source", "header_name" ], "properties": { "source": { "type": "string", "enum": [ "response_header" ], "description": "Part of the HTTP response to inspect. Only `response_header` is currently supported." }, "header_name": { "type": "string", "description": "HTTP response header name to inspect (case-insensitive)." }, "header_value": { "type": "string", "description": "Trips when the header value exactly equals this string (case-insensitive).\nMutually exclusive with `header_contains`. If neither is set, the signal trips whenever the header is present.\n" }, "header_contains": { "type": "string", "description": "Trips when the header value contains this substring (case-insensitive).\nMutually exclusive with `header_value`. If neither is set, the signal trips whenever the header is present.\n" } } } } } }, "default_cooldown": { "description": "How long to keep the circuit open (in nanoseconds).\nAccepted as a Go duration string on write (e.g. `\"30s\"`, `\"5m\"`); returned as an integer (nanoseconds) on read.\nDefaults to 30 seconds (30000000000 ns).\n", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(ns|us|µs|ms|s|m|h)$", "description": "Go duration string accepted on write." }, { "type": "integer", "format": "int64", "description": "Nanoseconds returned on read." } ] }, "cooldown_header": { "type": "string", "description": "Response header whose value (in milliseconds) overrides `default_cooldown`.\nFalls back to `default_cooldown` when the header is absent or unparsable.\n" } } } }, "count": { "type": "integer", "description": "Total number of policies returned." } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createCircuitBreakerPolicy", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Create circuit breaker policy", "description": "Creates a new circuit breaker policy and immediately activates it in the running gateway.\nReturns 409 if a policy with the same name already exists.\n", "tags": [ "Circuit Breaker" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "primary_provider", "primary_model", "fallback_provider", "fallback_model", "condition" ], "properties": { "name": { "type": "string", "description": "Unique name for this policy." }, "enabled": { "type": "boolean", "default": true, "description": "When `false`, the policy is registered but all hooks skip it." }, "primary_provider": { "type": "string", "description": "Provider to monitor (e.g. `azure`, `openai`)." }, "primary_model": { "type": "string", "description": "Model name as it appears in requests (e.g. `gpt-4o-ptu`)." }, "primary_key_ids": { "type": "array", "items": { "type": "string" }, "description": "API key UUIDs to track individually. Each key gets its own sub-circuit.\nThe main circuit opens only when all listed keys have tripped.\nLeave empty to use a single shared circuit for all keys serving this provider+model.\n" }, "fallback_provider": { "type": "string", "description": "Provider to route to when the circuit is open." }, "fallback_model": { "type": "string", "description": "Model to request from the fallback provider when the circuit is open." }, "condition": { "type": "object", "required": [ "signals" ], "properties": { "operator": { "type": "string", "enum": [ "OR", "AND" ], "default": "OR", "description": "How multiple signals are combined.\n`OR` (default): circuit opens when any signal matches.\n`AND`: circuit opens only when all signals match simultaneously.\n" }, "signals": { "type": "array", "minItems": 1, "description": "List of response signals to evaluate. At least one required.", "items": { "type": "object", "required": [ "source", "header_name" ], "properties": { "source": { "type": "string", "enum": [ "response_header" ], "description": "Part of the HTTP response to inspect. Only `response_header` is currently supported." }, "header_name": { "type": "string", "description": "HTTP response header name to inspect (case-insensitive)." }, "header_value": { "type": "string", "description": "Trips when the header value exactly equals this string (case-insensitive).\nMutually exclusive with `header_contains`. If neither is set, the signal trips whenever the header is present.\n" }, "header_contains": { "type": "string", "description": "Trips when the header value contains this substring (case-insensitive).\nMutually exclusive with `header_value`. If neither is set, the signal trips whenever the header is present.\n" } } } } } }, "default_cooldown": { "description": "How long to keep the circuit open (in nanoseconds).\nAccepted as a Go duration string on write (e.g. `\"30s\"`, `\"5m\"`); returned as an integer (nanoseconds) on read.\nDefaults to 30 seconds (30000000000 ns).\n", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(ns|us|µs|ms|s|m|h)$", "description": "Go duration string accepted on write." }, { "type": "integer", "format": "int64", "description": "Nanoseconds returned on read." } ] }, "cooldown_header": { "type": "string", "description": "Response header whose value (in milliseconds) overrides `default_cooldown`.\nFalls back to `default_cooldown` when the header is absent or unparsable.\n" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "primary_provider", "primary_model", "fallback_provider", "fallback_model", "condition" ], "properties": { "name": { "type": "string", "description": "Unique name for this policy." }, "enabled": { "type": "boolean", "default": true, "description": "When `false`, the policy is registered but all hooks skip it." }, "primary_provider": { "type": "string", "description": "Provider to monitor (e.g. `azure`, `openai`)." }, "primary_model": { "type": "string", "description": "Model name as it appears in requests (e.g. `gpt-4o-ptu`)." }, "primary_key_ids": { "type": "array", "items": { "type": "string" }, "description": "API key UUIDs to track individually. Each key gets its own sub-circuit.\nThe main circuit opens only when all listed keys have tripped.\nLeave empty to use a single shared circuit for all keys serving this provider+model.\n" }, "fallback_provider": { "type": "string", "description": "Provider to route to when the circuit is open." }, "fallback_model": { "type": "string", "description": "Model to request from the fallback provider when the circuit is open." }, "condition": { "type": "object", "required": [ "signals" ], "properties": { "operator": { "type": "string", "enum": [ "OR", "AND" ], "default": "OR", "description": "How multiple signals are combined.\n`OR` (default): circuit opens when any signal matches.\n`AND`: circuit opens only when all signals match simultaneously.\n" }, "signals": { "type": "array", "minItems": 1, "description": "List of response signals to evaluate. At least one required.", "items": { "type": "object", "required": [ "source", "header_name" ], "properties": { "source": { "type": "string", "enum": [ "response_header" ], "description": "Part of the HTTP response to inspect. Only `response_header` is currently supported." }, "header_name": { "type": "string", "description": "HTTP response header name to inspect (case-insensitive)." }, "header_value": { "type": "string", "description": "Trips when the header value exactly equals this string (case-insensitive).\nMutually exclusive with `header_contains`. If neither is set, the signal trips whenever the header is present.\n" }, "header_contains": { "type": "string", "description": "Trips when the header value contains this substring (case-insensitive).\nMutually exclusive with `header_value`. If neither is set, the signal trips whenever the header is present.\n" } } } } } }, "default_cooldown": { "description": "How long to keep the circuit open (in nanoseconds).\nAccepted as a Go duration string on write (e.g. `\"30s\"`, `\"5m\"`); returned as an integer (nanoseconds) on read.\nDefaults to 30 seconds (30000000000 ns).\n", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(ns|us|µs|ms|s|m|h)$", "description": "Go duration string accepted on write." }, { "type": "integer", "format": "int64", "description": "Nanoseconds returned on read." } ] }, "cooldown_header": { "type": "string", "description": "Response header whose value (in milliseconds) overrides `default_cooldown`.\nFalls back to `default_cooldown` when the header is absent or unparsable.\n" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "A policy with this name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/circuit-breaker/policies/{name}": { "put": { "operationId": "updateCircuitBreakerPolicy", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Update circuit breaker policy", "description": "Replaces a circuit breaker policy by name. The `name` field in the request body must match the URL parameter or be omitted.\nChanges take effect immediately in the running gateway.\n", "tags": [ "Circuit Breaker" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name of the policy to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "primary_provider", "primary_model", "fallback_provider", "fallback_model", "condition" ], "properties": { "name": { "type": "string", "description": "Unique name for this policy." }, "enabled": { "type": "boolean", "default": true, "description": "When `false`, the policy is registered but all hooks skip it." }, "primary_provider": { "type": "string", "description": "Provider to monitor (e.g. `azure`, `openai`)." }, "primary_model": { "type": "string", "description": "Model name as it appears in requests (e.g. `gpt-4o-ptu`)." }, "primary_key_ids": { "type": "array", "items": { "type": "string" }, "description": "API key UUIDs to track individually. Each key gets its own sub-circuit.\nThe main circuit opens only when all listed keys have tripped.\nLeave empty to use a single shared circuit for all keys serving this provider+model.\n" }, "fallback_provider": { "type": "string", "description": "Provider to route to when the circuit is open." }, "fallback_model": { "type": "string", "description": "Model to request from the fallback provider when the circuit is open." }, "condition": { "type": "object", "required": [ "signals" ], "properties": { "operator": { "type": "string", "enum": [ "OR", "AND" ], "default": "OR", "description": "How multiple signals are combined.\n`OR` (default): circuit opens when any signal matches.\n`AND`: circuit opens only when all signals match simultaneously.\n" }, "signals": { "type": "array", "minItems": 1, "description": "List of response signals to evaluate. At least one required.", "items": { "type": "object", "required": [ "source", "header_name" ], "properties": { "source": { "type": "string", "enum": [ "response_header" ], "description": "Part of the HTTP response to inspect. Only `response_header` is currently supported." }, "header_name": { "type": "string", "description": "HTTP response header name to inspect (case-insensitive)." }, "header_value": { "type": "string", "description": "Trips when the header value exactly equals this string (case-insensitive).\nMutually exclusive with `header_contains`. If neither is set, the signal trips whenever the header is present.\n" }, "header_contains": { "type": "string", "description": "Trips when the header value contains this substring (case-insensitive).\nMutually exclusive with `header_value`. If neither is set, the signal trips whenever the header is present.\n" } } } } } }, "default_cooldown": { "description": "How long to keep the circuit open (in nanoseconds).\nAccepted as a Go duration string on write (e.g. `\"30s\"`, `\"5m\"`); returned as an integer (nanoseconds) on read.\nDefaults to 30 seconds (30000000000 ns).\n", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(ns|us|µs|ms|s|m|h)$", "description": "Go duration string accepted on write." }, { "type": "integer", "format": "int64", "description": "Nanoseconds returned on read." } ] }, "cooldown_header": { "type": "string", "description": "Response header whose value (in milliseconds) overrides `default_cooldown`.\nFalls back to `default_cooldown` when the header is absent or unparsable.\n" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Policy updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "primary_provider", "primary_model", "fallback_provider", "fallback_model", "condition" ], "properties": { "name": { "type": "string", "description": "Unique name for this policy." }, "enabled": { "type": "boolean", "default": true, "description": "When `false`, the policy is registered but all hooks skip it." }, "primary_provider": { "type": "string", "description": "Provider to monitor (e.g. `azure`, `openai`)." }, "primary_model": { "type": "string", "description": "Model name as it appears in requests (e.g. `gpt-4o-ptu`)." }, "primary_key_ids": { "type": "array", "items": { "type": "string" }, "description": "API key UUIDs to track individually. Each key gets its own sub-circuit.\nThe main circuit opens only when all listed keys have tripped.\nLeave empty to use a single shared circuit for all keys serving this provider+model.\n" }, "fallback_provider": { "type": "string", "description": "Provider to route to when the circuit is open." }, "fallback_model": { "type": "string", "description": "Model to request from the fallback provider when the circuit is open." }, "condition": { "type": "object", "required": [ "signals" ], "properties": { "operator": { "type": "string", "enum": [ "OR", "AND" ], "default": "OR", "description": "How multiple signals are combined.\n`OR` (default): circuit opens when any signal matches.\n`AND`: circuit opens only when all signals match simultaneously.\n" }, "signals": { "type": "array", "minItems": 1, "description": "List of response signals to evaluate. At least one required.", "items": { "type": "object", "required": [ "source", "header_name" ], "properties": { "source": { "type": "string", "enum": [ "response_header" ], "description": "Part of the HTTP response to inspect. Only `response_header` is currently supported." }, "header_name": { "type": "string", "description": "HTTP response header name to inspect (case-insensitive)." }, "header_value": { "type": "string", "description": "Trips when the header value exactly equals this string (case-insensitive).\nMutually exclusive with `header_contains`. If neither is set, the signal trips whenever the header is present.\n" }, "header_contains": { "type": "string", "description": "Trips when the header value contains this substring (case-insensitive).\nMutually exclusive with `header_value`. If neither is set, the signal trips whenever the header is present.\n" } } } } } }, "default_cooldown": { "description": "How long to keep the circuit open (in nanoseconds).\nAccepted as a Go duration string on write (e.g. `\"30s\"`, `\"5m\"`); returned as an integer (nanoseconds) on read.\nDefaults to 30 seconds (30000000000 ns).\n", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(ns|us|µs|ms|s|m|h)$", "description": "Go duration string accepted on write." }, { "type": "integer", "format": "int64", "description": "Nanoseconds returned on read." } ] }, "cooldown_header": { "type": "string", "description": "Response header whose value (in milliseconds) overrides `default_cooldown`.\nFalls back to `default_cooldown` when the header is absent or unparsable.\n" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Policy not found." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteCircuitBreakerPolicy", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Delete circuit breaker policy", "description": "Deletes a circuit breaker policy by name and removes it from the running gateway.\nAny open circuits for this policy are discarded immediately.\n", "tags": [ "Circuit Breaker" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name of the policy to delete." } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Policy deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Policy not found." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/circuit-breaker/state": { "get": { "operationId": "getCircuitBreakerState", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Get circuit breaker state", "description": "Returns a snapshot of all currently-open circuits.\nMain circuits are keyed by policy name. Per-key sub-circuits are keyed by `\"\\x00\"`.\nCircuits not present in the map are closed.\n", "tags": [ "Circuit Breaker" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "circuits": { "type": "object", "description": "Map of circuit keys to their current state.\nMain circuit key: the policy name.\nSub-circuit key: `\"\\x00\"`.\n", "additionalProperties": { "type": "object", "description": "Runtime state of a single circuit (main circuit or per-key sub-circuit).", "properties": { "status": { "type": "string", "description": "Current circuit status. `open` means the circuit is tripped and requests are being rerouted." }, "opened_at": { "type": "string", "format": "date-time", "description": "When the circuit was last tripped." }, "cooldown": { "type": "integer", "format": "int64", "description": "Cooldown duration in nanoseconds." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the cooldown expires and the circuit will be probed again." } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/routing/rules": { "get": { "operationId": "listRoutingRules", "summary": "List routing rules", "description": "Returns a list of all routing rules configured for intelligent request routing across providers.", "tags": [ "Routing" ], "parameters": [ { "name": "scope", "in": "query", "description": "Filter routing rules by scope (global, team, customer, virtual_key)", "schema": { "type": "string" } }, { "name": "scope_id", "in": "query", "description": "Filter routing rules by scope ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRoutingRulesResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createRoutingRule", "summary": "Create routing rule", "description": "Creates a new CEL-based routing rule for intelligent request routing. Provider and model can be left empty to use the incoming request values.", "tags": [ "Routing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingRuleRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Routing rule created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRuleResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/routing/rules/{rule_id}": { "get": { "operationId": "getRoutingRule", "summary": "Get routing rule", "description": "Returns a specific routing rule by ID.", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/RoutingRule" } } } } } }, "404": { "description": "Routing rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateRoutingRule", "summary": "Update routing rule", "description": "Updates an existing routing rule's configuration.", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoutingRuleRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Routing rule updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRuleResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Routing rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteRoutingRule", "summary": "Delete routing rule", "description": "Deletes a routing rule.", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Routing rule deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Routing rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/routing/complexity-analyzer-config": { "get": { "operationId": "getComplexityAnalyzerConfig", "summary": "Get complexity analyzer config", "description": "Returns the full complexity analyzer runtime config, including tier thresholds and editable keyword lists. Returns built-in defaults if none have been configured.", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Complexity analyzer config retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "tier_boundaries", "keywords" ], "properties": { "tier_boundaries": { "type": "object", "description": "Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "additionalProperties": false, "required": [ "simple_medium", "medium_complex", "complex_reasoning" ], "properties": { "simple_medium": { "type": "number", "description": "Score boundary between SIMPLE and MEDIUM tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "description": "Score boundary between MEDIUM and COMPLEX tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "complex_reasoning": { "type": "number", "description": "Score boundary between COMPLEX and REASONING tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Editable keyword lists used by the complexity analyzer. Only the four user-facing\ndimensions are exposed; `reasoning_keywords` entries drive the reasoning tier\noverride. Matching is normalized to lowercase and duplicates are removed on save.\n", "additionalProperties": false, "required": [ "code_keywords", "reasoning_keywords", "technical_keywords", "simple_keywords" ], "properties": { "code_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reasoning_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "technical_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "simple_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateComplexityAnalyzerConfig", "summary": "Update complexity analyzer config", "description": "Replaces the full complexity analyzer runtime config and hot-reloads the routing plugin. Tier thresholds must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "tags": [ "Routing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "tier_boundaries", "keywords" ], "properties": { "tier_boundaries": { "type": "object", "description": "Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "additionalProperties": false, "required": [ "simple_medium", "medium_complex", "complex_reasoning" ], "properties": { "simple_medium": { "type": "number", "description": "Score boundary between SIMPLE and MEDIUM tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "description": "Score boundary between MEDIUM and COMPLEX tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "complex_reasoning": { "type": "number", "description": "Score boundary between COMPLEX and REASONING tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Editable keyword lists used by the complexity analyzer. Only the four user-facing\ndimensions are exposed; `reasoning_keywords` entries drive the reasoning tier\noverride. Matching is normalized to lowercase and duplicates are removed on save.\n", "additionalProperties": false, "required": [ "code_keywords", "reasoning_keywords", "technical_keywords", "simple_keywords" ], "properties": { "code_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reasoning_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "technical_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "simple_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Complexity analyzer config updated successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "tier_boundaries", "keywords" ], "properties": { "tier_boundaries": { "type": "object", "description": "Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "additionalProperties": false, "required": [ "simple_medium", "medium_complex", "complex_reasoning" ], "properties": { "simple_medium": { "type": "number", "description": "Score boundary between SIMPLE and MEDIUM tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "description": "Score boundary between MEDIUM and COMPLEX tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "complex_reasoning": { "type": "number", "description": "Score boundary between COMPLEX and REASONING tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Editable keyword lists used by the complexity analyzer. Only the four user-facing\ndimensions are exposed; `reasoning_keywords` entries drive the reasoning tier\noverride. Matching is normalized to lowercase and duplicates are removed on save.\n", "additionalProperties": false, "required": [ "code_keywords", "reasoning_keywords", "technical_keywords", "simple_keywords" ], "properties": { "code_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reasoning_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "technical_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "simple_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/routing/complexity-analyzer-config/reset": { "post": { "operationId": "resetComplexityAnalyzerConfig", "summary": "Reset complexity analyzer config", "description": "Restores the built-in complexity analyzer runtime config defaults and hot-reloads the routing plugin.", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Complexity analyzer config reset successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "tier_boundaries", "keywords" ], "properties": { "tier_boundaries": { "type": "object", "description": "Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "additionalProperties": false, "required": [ "simple_medium", "medium_complex", "complex_reasoning" ], "properties": { "simple_medium": { "type": "number", "description": "Score boundary between SIMPLE and MEDIUM tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "description": "Score boundary between MEDIUM and COMPLEX tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "complex_reasoning": { "type": "number", "description": "Score boundary between COMPLEX and REASONING tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Editable keyword lists used by the complexity analyzer. Only the four user-facing\ndimensions are exposed; `reasoning_keywords` entries drive the reasoning tier\noverride. Matching is normalized to lowercase and duplicates are removed on save.\n", "additionalProperties": false, "required": [ "code_keywords", "reasoning_keywords", "technical_keywords", "simple_keywords" ], "properties": { "code_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reasoning_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "technical_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "simple_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/routing-rules": { "get": { "operationId": "listRoutingRulesLegacy", "deprecated": true, "summary": "List routing rules (deprecated path)", "description": "Returns a list of all routing rules configured for intelligent request routing across providers. Deprecated, use /api/routing/rules instead. This path is kept for backwards compatibility and behaves identically.", "tags": [ "Routing" ], "parameters": [ { "name": "scope", "in": "query", "description": "Filter routing rules by scope (global, team, customer, virtual_key)", "schema": { "type": "string" } }, { "name": "scope_id", "in": "query", "description": "Filter routing rules by scope ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRoutingRulesResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createRoutingRuleLegacy", "deprecated": true, "summary": "Create routing rule (deprecated path)", "description": "Creates a new CEL-based routing rule for intelligent request routing. Provider and model can be left empty to use the incoming request values. Deprecated, use /api/routing/rules instead. This path is kept for backwards compatibility and behaves identically.", "tags": [ "Routing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingRuleRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Routing rule created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRuleResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/routing-rules/{rule_id}": { "get": { "operationId": "getRoutingRuleLegacy", "deprecated": true, "summary": "Get routing rule (deprecated path)", "description": "Returns a specific routing rule by ID. Deprecated, use /api/routing/rules/{rule_id} instead. This path is kept for backwards compatibility and behaves identically.", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/RoutingRule" } } } } } }, "404": { "description": "Routing rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateRoutingRuleLegacy", "deprecated": true, "summary": "Update routing rule (deprecated path)", "description": "Updates an existing routing rule's configuration. Deprecated, use /api/routing/rules/{rule_id} instead. This path is kept for backwards compatibility and behaves identically.", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoutingRuleRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Routing rule updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRuleResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Routing rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteRoutingRuleLegacy", "deprecated": true, "summary": "Delete routing rule (deprecated path)", "description": "Deletes a routing rule. Deprecated, use /api/routing/rules/{rule_id} instead. This path is kept for backwards compatibility and behaves identically.", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Routing rule deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Routing rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/complexity-analyzer-config": { "get": { "operationId": "getComplexityAnalyzerConfigLegacy", "deprecated": true, "summary": "Get complexity analyzer config (deprecated path)", "description": "Returns the full complexity analyzer runtime config, including tier thresholds and editable keyword lists. Returns built-in defaults if none have been configured. Deprecated, use /api/routing/complexity-analyzer-config instead. This path is kept for backwards compatibility and behaves identically.", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Complexity analyzer config retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "tier_boundaries", "keywords" ], "properties": { "tier_boundaries": { "type": "object", "description": "Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "additionalProperties": false, "required": [ "simple_medium", "medium_complex", "complex_reasoning" ], "properties": { "simple_medium": { "type": "number", "description": "Score boundary between SIMPLE and MEDIUM tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "description": "Score boundary between MEDIUM and COMPLEX tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "complex_reasoning": { "type": "number", "description": "Score boundary between COMPLEX and REASONING tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Editable keyword lists used by the complexity analyzer. Only the four user-facing\ndimensions are exposed; `reasoning_keywords` entries drive the reasoning tier\noverride. Matching is normalized to lowercase and duplicates are removed on save.\n", "additionalProperties": false, "required": [ "code_keywords", "reasoning_keywords", "technical_keywords", "simple_keywords" ], "properties": { "code_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reasoning_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "technical_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "simple_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateComplexityAnalyzerConfigLegacy", "deprecated": true, "summary": "Update complexity analyzer config (deprecated path)", "description": "Replaces the full complexity analyzer runtime config and hot-reloads the routing plugin. Tier thresholds must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1. Deprecated, use /api/routing/complexity-analyzer-config instead. This path is kept for backwards compatibility and behaves identically.", "tags": [ "Routing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "tier_boundaries", "keywords" ], "properties": { "tier_boundaries": { "type": "object", "description": "Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "additionalProperties": false, "required": [ "simple_medium", "medium_complex", "complex_reasoning" ], "properties": { "simple_medium": { "type": "number", "description": "Score boundary between SIMPLE and MEDIUM tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "description": "Score boundary between MEDIUM and COMPLEX tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "complex_reasoning": { "type": "number", "description": "Score boundary between COMPLEX and REASONING tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Editable keyword lists used by the complexity analyzer. Only the four user-facing\ndimensions are exposed; `reasoning_keywords` entries drive the reasoning tier\noverride. Matching is normalized to lowercase and duplicates are removed on save.\n", "additionalProperties": false, "required": [ "code_keywords", "reasoning_keywords", "technical_keywords", "simple_keywords" ], "properties": { "code_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reasoning_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "technical_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "simple_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Complexity analyzer config updated successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "tier_boundaries", "keywords" ], "properties": { "tier_boundaries": { "type": "object", "description": "Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "additionalProperties": false, "required": [ "simple_medium", "medium_complex", "complex_reasoning" ], "properties": { "simple_medium": { "type": "number", "description": "Score boundary between SIMPLE and MEDIUM tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "description": "Score boundary between MEDIUM and COMPLEX tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "complex_reasoning": { "type": "number", "description": "Score boundary between COMPLEX and REASONING tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Editable keyword lists used by the complexity analyzer. Only the four user-facing\ndimensions are exposed; `reasoning_keywords` entries drive the reasoning tier\noverride. Matching is normalized to lowercase and duplicates are removed on save.\n", "additionalProperties": false, "required": [ "code_keywords", "reasoning_keywords", "technical_keywords", "simple_keywords" ], "properties": { "code_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reasoning_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "technical_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "simple_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/complexity-analyzer-config/reset": { "post": { "operationId": "resetComplexityAnalyzerConfigLegacy", "deprecated": true, "summary": "Reset complexity analyzer config (deprecated path)", "description": "Restores the built-in complexity analyzer runtime config defaults and hot-reloads the routing plugin. Deprecated, use /api/routing/complexity-analyzer-config/reset instead. This path is kept for backwards compatibility and behaves identically.", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Complexity analyzer config reset successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "tier_boundaries", "keywords" ], "properties": { "tier_boundaries": { "type": "object", "description": "Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.", "additionalProperties": false, "required": [ "simple_medium", "medium_complex", "complex_reasoning" ], "properties": { "simple_medium": { "type": "number", "description": "Score boundary between SIMPLE and MEDIUM tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "description": "Score boundary between MEDIUM and COMPLEX tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "complex_reasoning": { "type": "number", "description": "Score boundary between COMPLEX and REASONING tiers", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Editable keyword lists used by the complexity analyzer. Only the four user-facing\ndimensions are exposed; `reasoning_keywords` entries drive the reasoning tier\noverride. Matching is normalized to lowercase and duplicates are removed on save.\n", "additionalProperties": false, "required": [ "code_keywords", "reasoning_keywords", "technical_keywords", "simple_keywords" ], "properties": { "code_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reasoning_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "technical_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "simple_keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs": { "get": { "operationId": "getLogs", "summary": "Get logs", "description": "Retrieves logs with filtering, search, and pagination via query parameters.\n", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by (routing-rule, governance, or loadbalancing)", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of logs to return (default 50, max 1000)", "schema": { "type": "integer", "default": 50, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Number of logs to skip", "schema": { "type": "integer", "default": 0 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "schema": { "type": "string", "enum": [ "timestamp", "latency", "tokens", "cost" ], "default": "timestamp" } }, { "name": "order", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchLogsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteLogs", "summary": "Delete logs", "description": "Deletes logs by their IDs.", "tags": [ "Logging" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteLogsRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Logs deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/{id}": { "get": { "operationId": "getLogById", "summary": "Get a single log entry", "description": "Retrieves a single log entry by its ID.", "tags": [ "Logging" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Log entry ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogEntry" } } } }, "404": { "description": "Log not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/sessions/{session_id}": { "get": { "operationId": "getLogSessionById", "summary": "Get logs for a session", "description": "Returns the paginated logs belonging to a single parent-request session\n(grouped by `parent_request_id`). Sorted ascending by timestamp by default.\n", "tags": [ "Logging" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "Parent request ID identifying the session", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of logs to return (default 200, max 200)", "schema": { "type": "integer", "default": 200, "maximum": 200 } }, { "name": "offset", "in": "query", "description": "Number of logs to skip", "schema": { "type": "integer", "default": 0 } }, { "name": "order", "in": "query", "description": "Sort order (default `asc`)", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Session logs retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated logs for a single parent-request session", "properties": { "session_id": { "type": "string" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } }, "pagination": { "type": "object", "description": "Pagination metadata. Session logs are always sorted by timestamp; the `sort_by` field is not configurable.", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of items matching the query" } } }, "count": { "type": "integer", "format": "int64", "description": "Total log count for this session" }, "returned_count": { "type": "integer", "description": "Number of logs returned in this response" }, "has_more": { "type": "boolean" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/sessions/{session_id}/summary": { "get": { "operationId": "getLogSessionSummaryById", "summary": "Get aggregate totals for a session", "description": "Returns aggregate request count, token usage, cost, and duration for a single session.", "tags": [ "Logging" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "Parent request ID identifying the session", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Session summary retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Aggregate totals for a single parent-request session", "properties": { "session_id": { "type": "string" }, "count": { "type": "integer", "format": "int64" }, "total_cost": { "type": "number" }, "total_tokens": { "type": "integer", "format": "int64" }, "started_at": { "type": "string", "description": "Timestamp of the first log in the session (RFC3339 nanos)" }, "latest_at": { "type": "string", "description": "Timestamp of the most recent log in the session (RFC3339 nanos)" }, "duration_ms": { "type": "integer", "format": "int64" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/stats": { "get": { "operationId": "getLogsStats", "summary": "Get log statistics", "description": "Returns statistics for logs matching the specified filters.", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by (routing-rule, governance, or loadbalancing)", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogStats" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram": { "get": { "operationId": "getLogsHistogram", "summary": "Get request count histogram", "description": "Returns time-bucketed request counts. Bucket size is auto-calculated from the time range.\n", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "aliases", "in": "query", "description": "Comma-separated list of model aliases to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "team_ids", "in": "query", "description": "Comma-separated list of team IDs to filter by", "schema": { "type": "string" } }, { "name": "customer_ids", "in": "query", "description": "Comma-separated list of customer IDs to filter by", "schema": { "type": "string" } }, { "name": "user_ids", "in": "query", "description": "Comma-separated list of user IDs to filter by", "schema": { "type": "string" } }, { "name": "business_unit_ids", "in": "query", "description": "Comma-separated list of business unit IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "period", "in": "query", "description": "Relative time period filter", "schema": { "type": "string" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "stop_reasons", "in": "query", "description": "Comma-separated list of stop reasons to filter by", "schema": { "type": "string" } }, { "name": "cache_hit_types", "in": "query", "description": "Comma-separated list of cache hit types to filter by", "schema": { "type": "string" } }, { "name": "parent_request_id", "in": "query", "description": "Parent request ID to filter by", "schema": { "type": "string" } }, { "name": "metadata_", "in": "query", "description": "Metadata filter where is the metadata key to match", "schema": { "type": "string" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed request count histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed request count", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "format": "int64" }, "success": { "type": "integer", "format": "int64" }, "error": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/tokens": { "get": { "operationId": "getLogsTokenHistogram", "summary": "Get token usage histogram", "description": "Returns time-bucketed token usage (prompt, completion, total).", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed token usage histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed token usage", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "prompt_tokens": { "type": "integer", "format": "int64" }, "completion_tokens": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/cost": { "get": { "operationId": "getLogsCostHistogram", "summary": "Get cost histogram", "description": "Returns time-bucketed cost data with model breakdown.", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed cost histogram with model breakdown", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed cost data with model breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total_cost": { "type": "number" }, "by_model": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Cost breakdown by model name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "models": { "type": "array", "items": { "type": "string" }, "description": "List of models present in the histogram" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/models": { "get": { "operationId": "getLogsModelHistogram", "summary": "Get model usage histogram", "description": "Returns time-bucketed model usage with success/error breakdown.", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed model usage histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed model usage with success/error breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_model": { "type": "object", "additionalProperties": { "type": "object", "description": "Usage statistics for a single model", "properties": { "total": { "type": "integer", "format": "int64" }, "success": { "type": "integer", "format": "int64" }, "error": { "type": "integer", "format": "int64" } } }, "description": "Usage breakdown by model name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "models": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/latency": { "get": { "operationId": "getLogsLatencyHistogram", "summary": "Get latency histogram", "description": "Returns time-bucketed latency percentiles (avg, p90, p95, p99).", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed latency histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed latency percentiles", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "avg_latency": { "type": "number" }, "p90_latency": { "type": "number" }, "p95_latency": { "type": "number" }, "p99_latency": { "type": "number" }, "total_requests": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/cost/by-provider": { "get": { "operationId": "getLogsProviderCostHistogram", "summary": "Get cost histogram by provider", "description": "Returns time-bucketed cost data with provider breakdown.", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed cost histogram with provider breakdown", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed cost data with provider breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total_cost": { "type": "number" }, "by_provider": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Cost breakdown by provider name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "providers": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/tokens/by-provider": { "get": { "operationId": "getLogsProviderTokenHistogram", "summary": "Get token histogram by provider", "description": "Returns time-bucketed token usage with provider breakdown.", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed token histogram with provider breakdown", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed token usage with provider breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_provider": { "type": "object", "additionalProperties": { "type": "object", "description": "Token statistics for a single provider", "properties": { "prompt_tokens": { "type": "integer", "format": "int64" }, "completion_tokens": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "description": "Token usage breakdown by provider name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "providers": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/latency/by-provider": { "get": { "operationId": "getLogsProviderLatencyHistogram", "summary": "Get latency histogram by provider", "description": "Returns time-bucketed latency percentiles with provider breakdown.", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed latency histogram with provider breakdown", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed latency data with provider breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_provider": { "type": "object", "additionalProperties": { "type": "object", "description": "Latency statistics for a single provider", "properties": { "avg_latency": { "type": "number" }, "p90_latency": { "type": "number" }, "p95_latency": { "type": "number" }, "p99_latency": { "type": "number" }, "total_requests": { "type": "integer", "format": "int64" } } }, "description": "Latency breakdown by provider name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "providers": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/cost/by-dimension": { "get": { "operationId": "getLogsDimensionCostHistogram", "summary": "Get cost histogram by dimension", "description": "Returns time-bucketed cost data grouped by an arbitrary dimension\n(`provider`, `team_id`, `customer_id`, `user_id`, `business_unit_id`).\nThe dimension is supplied via the required `dimension` query parameter.\n", "tags": [ "Logging" ], "parameters": [ { "name": "dimension", "in": "query", "required": true, "description": "Grouping dimension", "schema": { "type": "string", "description": "Grouping dimension for dimension-aware histograms. Used by the\n`/api/logs/histogram/{cost,tokens,latency}/by-dimension` endpoints.\n", "enum": [ "provider", "team_id", "customer_id", "user_id", "business_unit_id" ] } }, { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Dimension cost histogram retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Dimension-grouped cost histogram result", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed cost data grouped by an arbitrary dimension", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total_cost": { "type": "number" }, "by_dimension": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Cost breakdown keyed by the dimension value" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "dimension": { "type": "string", "description": "Grouping dimension for dimension-aware histograms. Used by the\n`/api/logs/histogram/{cost,tokens,latency}/by-dimension` endpoints.\n", "enum": [ "provider", "team_id", "customer_id", "user_id", "business_unit_id" ] }, "dimension_values": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/tokens/by-dimension": { "get": { "operationId": "getLogsDimensionTokenHistogram", "summary": "Get token histogram by dimension", "description": "Returns time-bucketed token usage grouped by an arbitrary dimension.\nSee `getLogsDimensionCostHistogram` for the list of supported dimensions.\n", "tags": [ "Logging" ], "parameters": [ { "name": "dimension", "in": "query", "required": true, "description": "Grouping dimension", "schema": { "type": "string", "description": "Grouping dimension for dimension-aware histograms. Used by the\n`/api/logs/histogram/{cost,tokens,latency}/by-dimension` endpoints.\n", "enum": [ "provider", "team_id", "customer_id", "user_id", "business_unit_id" ] } }, { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Dimension token histogram retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Dimension-grouped token histogram result", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed token usage grouped by an arbitrary dimension", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_dimension": { "type": "object", "additionalProperties": { "type": "object", "description": "Token statistics for a single dimension value", "properties": { "prompt_tokens": { "type": "integer", "format": "int64" }, "completion_tokens": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } } } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "dimension": { "type": "string", "description": "Grouping dimension for dimension-aware histograms. Used by the\n`/api/logs/histogram/{cost,tokens,latency}/by-dimension` endpoints.\n", "enum": [ "provider", "team_id", "customer_id", "user_id", "business_unit_id" ] }, "dimension_values": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/latency/by-dimension": { "get": { "operationId": "getLogsDimensionLatencyHistogram", "summary": "Get latency histogram by dimension", "description": "Returns time-bucketed latency percentiles (avg, p90, p95, p99) grouped by\nan arbitrary dimension.\n", "tags": [ "Logging" ], "parameters": [ { "name": "dimension", "in": "query", "required": true, "description": "Grouping dimension", "schema": { "type": "string", "description": "Grouping dimension for dimension-aware histograms. Used by the\n`/api/logs/histogram/{cost,tokens,latency}/by-dimension` endpoints.\n", "enum": [ "provider", "team_id", "customer_id", "user_id", "business_unit_id" ] } }, { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Dimension latency histogram retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Dimension-grouped latency histogram result", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed latency data grouped by an arbitrary dimension", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_dimension": { "type": "object", "additionalProperties": { "type": "object", "description": "Latency statistics for a single dimension value", "properties": { "avg_latency": { "type": "number" }, "p90_latency": { "type": "number" }, "p95_latency": { "type": "number" }, "p99_latency": { "type": "number" }, "total_requests": { "type": "integer", "format": "int64" } } } } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "dimension": { "type": "string", "description": "Grouping dimension for dimension-aware histograms. Used by the\n`/api/logs/histogram/{cost,tokens,latency}/by-dimension` endpoints.\n", "enum": [ "provider", "team_id", "customer_id", "user_id", "business_unit_id" ] }, "dimension_values": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/dropped": { "get": { "operationId": "getDroppedRequests", "summary": "Get dropped requests count", "description": "Returns the number of dropped requests.", "tags": [ "Logging" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Dropped requests response", "properties": { "dropped_requests": { "type": "integer", "format": "int64" } } } } } } } } }, "/api/logs/filterdata": { "get": { "operationId": "getAvailableFilterData", "summary": "Get available filter data", "description": "Returns all unique filter data from logs (models, keys, virtual keys).", "tags": [ "Logging" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Available filter data response", "properties": { "models": { "type": "array", "items": { "type": "string" } }, "selected_keys": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } }, "virtual_keys": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualKey" } }, "routing_rules": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingRule" }, "description": "Available routing rules for filtering" }, "routing_engines": { "type": "array", "items": { "type": "string" }, "description": "Available routing engine types (routing-rule, governance, loadbalancing)" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/rankings": { "get": { "operationId": "getModelRankings", "summary": "Get model usage rankings", "description": "Returns models ranked by usage with trend percentages versus the previous\ncomparable period. Accepts the same filter parameters as the histogram\nendpoints.\n", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "aliases", "in": "query", "description": "Comma-separated list of model aliases to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "team_ids", "in": "query", "description": "Comma-separated list of team IDs to filter by", "schema": { "type": "string" } }, { "name": "customer_ids", "in": "query", "description": "Comma-separated list of customer IDs to filter by", "schema": { "type": "string" } }, { "name": "user_ids", "in": "query", "description": "Comma-separated list of user IDs to filter by", "schema": { "type": "string" } }, { "name": "business_unit_ids", "in": "query", "description": "Comma-separated list of business unit IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "period", "in": "query", "description": "Relative time period filter", "schema": { "type": "string" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "stop_reasons", "in": "query", "description": "Comma-separated list of stop reasons to filter by", "schema": { "type": "string" } }, { "name": "cache_hit_types", "in": "query", "description": "Comma-separated list of cache hit types to filter by", "schema": { "type": "string" } }, { "name": "parent_request_id", "in": "query", "description": "Parent request ID to filter by", "schema": { "type": "string" } }, { "name": "metadata_", "in": "query", "description": "Metadata filter where is the metadata key to match", "schema": { "type": "string" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of ranked rows to return. Defaults to 100. Ignored when\n`all=true`.\n", "schema": { "type": "integer", "minimum": 1, "default": 100 } }, { "name": "all", "in": "query", "description": "When true, returns every ranked entity with no row cap. Intended for\nexports (CSV / PDF), which must not be truncated.\n", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Model rankings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Models ranked by usage with trend comparison", "properties": { "rankings": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Aggregated stats for a single model over the query period", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "total_requests": { "type": "integer", "format": "int64" }, "success_count": { "type": "integer", "format": "int64" }, "success_rate": { "type": "number" }, "total_tokens": { "type": "integer", "format": "int64" }, "total_cost": { "type": "number" }, "avg_latency": { "type": "number" } } }, { "type": "object", "properties": { "trend": { "type": "object", "description": "Percentage change versus the previous comparable period", "properties": { "has_previous_period": { "type": "boolean" }, "requests_trend": { "type": "number" }, "tokens_trend": { "type": "number" }, "cost_trend": { "type": "number" }, "latency_trend": { "type": "number" } } } } } ] } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/dashboard": { "get": { "operationId": "getDashboard", "summary": "Get consolidated dashboard data", "description": "Returns every metric shown on the workspace dashboard in a single\nresponse: overview totals and histograms, provider usage, model rankings,\ndimension rankings (team, user, virtual key, customer, business unit), and\nMCP usage. Intended for external integrations that want the full dashboard\nin one call rather than orchestrating the individual endpoints.\n\nAccepts the same LLM filter parameters as the histogram and rankings\nendpoints, plus the MCP filter parameters (`tool_names`, `server_labels`)\nwhich apply to the `mcp` section. Filters are applied once and every\nsection is computed against the same time window and bucket size. The\nrequest fails as a whole if any section cannot be computed, so the payload\nis always complete.\n", "tags": [ "Logging" ], "parameters": [ { "name": "providers", "in": "query", "description": "Comma-separated list of providers to filter by", "schema": { "type": "string" } }, { "name": "models", "in": "query", "description": "Comma-separated list of models to filter by", "schema": { "type": "string" } }, { "name": "aliases", "in": "query", "description": "Comma-separated list of model aliases to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string" } }, { "name": "objects", "in": "query", "description": "Comma-separated list of object types to filter by", "schema": { "type": "string" } }, { "name": "selected_key_ids", "in": "query", "description": "Comma-separated list of selected key IDs to filter by", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "team_ids", "in": "query", "description": "Comma-separated list of team IDs to filter by", "schema": { "type": "string" } }, { "name": "customer_ids", "in": "query", "description": "Comma-separated list of customer IDs to filter by", "schema": { "type": "string" } }, { "name": "user_ids", "in": "query", "description": "Comma-separated list of user IDs to filter by", "schema": { "type": "string" } }, { "name": "business_unit_ids", "in": "query", "description": "Comma-separated list of business unit IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule IDs to filter by", "schema": { "type": "string" } }, { "name": "routing_engine_used", "in": "query", "description": "Comma-separated list of routing engines to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "period", "in": "query", "description": "Relative time period filter", "schema": { "type": "string" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "min_tokens", "in": "query", "description": "Minimum tokens filter", "schema": { "type": "integer" } }, { "name": "max_tokens", "in": "query", "description": "Maximum tokens filter", "schema": { "type": "integer" } }, { "name": "min_cost", "in": "query", "description": "Minimum cost filter", "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "description": "Maximum cost filter", "schema": { "type": "number" } }, { "name": "missing_cost_only", "in": "query", "description": "Only show logs with missing cost", "schema": { "type": "boolean" } }, { "name": "stop_reasons", "in": "query", "description": "Comma-separated list of stop reasons to filter by", "schema": { "type": "string" } }, { "name": "cache_hit_types", "in": "query", "description": "Comma-separated list of cache hit types to filter by", "schema": { "type": "string" } }, { "name": "parent_request_id", "in": "query", "description": "Parent request ID to filter by", "schema": { "type": "string" } }, { "name": "metadata_", "in": "query", "description": "Metadata filter where is the metadata key to match", "schema": { "type": "string" } }, { "name": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } }, { "name": "tool_names", "in": "query", "description": "Comma-separated list of MCP tool names to filter the MCP section by", "schema": { "type": "string" } }, { "name": "server_labels", "in": "query", "description": "Comma-separated list of MCP server labels to filter the MCP section by", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of ranked rows to return. Defaults to 100. Ignored when\n`all=true`.\n", "schema": { "type": "integer", "minimum": 1, "default": 100 } }, { "name": "all", "in": "query", "description": "When true, returns every ranked entity with no row cap. Intended for\nexports (CSV / PDF), which must not be truncated.\n", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Dashboard data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Consolidated payload containing every metric shown on the workspace\ndashboard. Each section mirrors the response of its dedicated endpoint, so\nconsumers can integrate a single call instead of orchestrating many.\n", "properties": { "meta": { "type": "object", "description": "Parameters the dashboard data was computed with", "properties": { "generated_at": { "type": "string", "format": "date-time", "description": "UTC time the response was assembled" }, "bucket_size_seconds": { "type": "integer", "format": "int64", "description": "Width of every histogram bucket, derived from the time range" }, "start_time": { "type": "string", "format": "date-time", "description": "Resolved start of the queried range" }, "end_time": { "type": "string", "format": "date-time", "description": "Resolved end of the queried range" } } }, "overview": { "type": "object", "description": "Overview tab metrics", "properties": { "stats": { "$ref": "#/components/schemas/LogStats" }, "requests": { "type": "object", "description": "Time-bucketed request count histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed request count", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "format": "int64" }, "success": { "type": "integer", "format": "int64" }, "error": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } }, "tokens": { "type": "object", "description": "Time-bucketed token usage histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed token usage", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "prompt_tokens": { "type": "integer", "format": "int64" }, "completion_tokens": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } }, "cost": { "type": "object", "description": "Time-bucketed cost histogram with model breakdown", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed cost data with model breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total_cost": { "type": "number" }, "by_model": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Cost breakdown by model name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "models": { "type": "array", "items": { "type": "string" }, "description": "List of models present in the histogram" } } }, "models": { "type": "object", "description": "Time-bucketed model usage histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed model usage with success/error breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_model": { "type": "object", "additionalProperties": { "type": "object", "description": "Usage statistics for a single model", "properties": { "total": { "type": "integer", "format": "int64" }, "success": { "type": "integer", "format": "int64" }, "error": { "type": "integer", "format": "int64" } } }, "description": "Usage breakdown by model name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "models": { "type": "array", "items": { "type": "string" } } } }, "latency": { "type": "object", "description": "Time-bucketed latency histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed latency percentiles", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "avg_latency": { "type": "number" }, "p90_latency": { "type": "number" }, "p95_latency": { "type": "number" }, "p99_latency": { "type": "number" }, "total_requests": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } } } }, "provider_usage": { "type": "object", "description": "Provider Usage tab metrics", "properties": { "cost": { "type": "object", "description": "Time-bucketed cost histogram with provider breakdown", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed cost data with provider breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total_cost": { "type": "number" }, "by_provider": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Cost breakdown by provider name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "providers": { "type": "array", "items": { "type": "string" } } } }, "tokens": { "type": "object", "description": "Time-bucketed token histogram with provider breakdown", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed token usage with provider breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_provider": { "type": "object", "additionalProperties": { "type": "object", "description": "Token statistics for a single provider", "properties": { "prompt_tokens": { "type": "integer", "format": "int64" }, "completion_tokens": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "description": "Token usage breakdown by provider name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "providers": { "type": "array", "items": { "type": "string" } } } }, "latency": { "type": "object", "description": "Time-bucketed latency histogram with provider breakdown", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed latency data with provider breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_provider": { "type": "object", "additionalProperties": { "type": "object", "description": "Latency statistics for a single provider", "properties": { "avg_latency": { "type": "number" }, "p90_latency": { "type": "number" }, "p95_latency": { "type": "number" }, "p99_latency": { "type": "number" }, "total_requests": { "type": "integer", "format": "int64" } } }, "description": "Latency breakdown by provider name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "providers": { "type": "array", "items": { "type": "string" } } } } } }, "model_rankings": { "type": "object", "description": "Model Rankings tab data", "properties": { "rankings": { "type": "object", "description": "Models ranked by usage with trend comparison", "properties": { "rankings": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Aggregated stats for a single model over the query period", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "total_requests": { "type": "integer", "format": "int64" }, "success_count": { "type": "integer", "format": "int64" }, "success_rate": { "type": "number" }, "total_tokens": { "type": "integer", "format": "int64" }, "total_cost": { "type": "number" }, "avg_latency": { "type": "number" } } }, { "type": "object", "properties": { "trend": { "type": "object", "description": "Percentage change versus the previous comparable period", "properties": { "has_previous_period": { "type": "boolean" }, "requests_trend": { "type": "number" }, "tokens_trend": { "type": "number" }, "cost_trend": { "type": "number" }, "latency_trend": { "type": "number" } } } } } ] } } } }, "histogram": { "type": "object", "description": "Time-bucketed model usage histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed model usage with success/error breakdown", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_model": { "type": "object", "additionalProperties": { "type": "object", "description": "Usage statistics for a single model", "properties": { "total": { "type": "integer", "format": "int64" }, "success": { "type": "integer", "format": "int64" }, "error": { "type": "integer", "format": "int64" } } }, "description": "Usage breakdown by model name" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "models": { "type": "array", "items": { "type": "string" } } } } } }, "dimension_rankings": { "type": "object", "description": "Ranking tables keyed by dimension (`team`, `user`, `virtual_key`,\n`customer`, `business_unit`); each value is that dimension's rankings.\n", "additionalProperties": { "type": "object", "description": "Dimension values ranked by usage with trend comparison", "properties": { "rankings": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Aggregated usage for a single dimension value (team, user, virtual key, etc.)", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "total_requests": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" }, "total_cost": { "type": "number" } } }, { "type": "object", "properties": { "trend": { "type": "object", "description": "Percentage change versus the previous comparable period", "properties": { "has_previous_period": { "type": "boolean" }, "requests_trend": { "type": "number" }, "tokens_trend": { "type": "number" }, "cost_trend": { "type": "number" } } } } } ] } }, "dimension": { "type": "string", "description": "Entity used to group dimension rankings", "enum": [ "team", "customer", "business_unit", "user", "virtual_key" ] }, "total_actual_requests": { "type": "integer", "format": "int64", "description": "Distinct request count over the attributed population. Only set for\nfan-out dimensions (team, customer, business_unit) on Postgres.\n" }, "total_attributed_requests": { "type": "integer", "format": "int64", "description": "Requests credited to every dimension value they touch; the sum can\nexceed the real request count. Only set for fan-out dimensions.\n" } } } }, "mcp": { "type": "object", "description": "MCP usage tab metrics", "properties": { "volume": { "type": "object", "description": "Time-bucketed MCP tool call volume histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed MCP tool call volume", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "format": "int64" }, "success": { "type": "integer", "format": "int64" }, "error": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } }, "cost": { "type": "object", "description": "Time-bucketed MCP cost histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed MCP cost data", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total_cost": { "type": "number" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } }, "top_tools": { "type": "object", "description": "Top MCP tools by call count (limit 10)", "properties": { "tools": { "type": "array", "items": { "type": "object", "description": "Aggregated stats for a single MCP tool", "properties": { "tool_name": { "type": "string" }, "count": { "type": "integer", "format": "int64" }, "cost": { "type": "number" } } } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/recalculate-cost": { "post": { "operationId": "recalculateLogCosts", "summary": "Recalculate log costs", "description": "Starts an asynchronous background job that recalculates log costs in batches.\nThe returned payload is a job status object that can be polled via the status endpoint.\n", "tags": [ "Logging" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecalculateCostRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "202": { "description": "Cost recalculation job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecalculateCostResponse" } } } }, "409": { "description": "A recalculation job is already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecalculateCostResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Background job runner is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/recalculate-cost/status": { "get": { "operationId": "getRecalculateCostStatus", "summary": "Get log cost recalculation status", "description": "Returns the current status of a log cost recalculation job.\nWhen `id` is omitted, the current in-flight job is returned, or `idle` when no job is running.\n", "tags": [ "Logging" ], "parameters": [ { "name": "id", "in": "query", "description": "Optional recalculation job ID to fetch", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Recalculation job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecalculateCostResponse" } } } }, "404": { "description": "Recalculation job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "503": { "description": "Background job runner is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp-logs": { "get": { "operationId": "getMCPLogs", "summary": "Get MCP tool logs", "description": "Retrieves MCP tool execution logs with filtering, search, and pagination via query parameters.\n", "tags": [ "Logging" ], "parameters": [ { "name": "tool_names", "in": "query", "description": "Comma-separated list of tool names to filter by", "schema": { "type": "string" } }, { "name": "server_labels", "in": "query", "description": "Comma-separated list of server labels to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by (processing, success, error)", "schema": { "type": "string", "enum": [ "processing", "success", "error" ] } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "llm_request_ids", "in": "query", "description": "Comma-separated list of LLM request IDs to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter (milliseconds)", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter (milliseconds)", "schema": { "type": "number" } }, { "name": "content_search", "in": "query", "description": "Search in tool arguments and results", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of logs to return (default 50, max 1000)", "schema": { "type": "integer", "default": 50, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Number of logs to skip", "schema": { "type": "integer", "default": 0 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "schema": { "type": "string", "enum": [ "timestamp", "latency", "cost" ], "default": "timestamp" } }, { "name": "order", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Search MCP logs response", "properties": { "logs": { "type": "array", "items": { "type": "object", "description": "MCP tool execution log entry", "properties": { "id": { "type": "string", "description": "Unique identifier for the log entry" }, "llm_request_id": { "type": "string", "description": "Links to the LLM request that triggered this tool call" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the tool execution started" }, "tool_name": { "type": "string", "description": "Name of the MCP tool that was executed" }, "server_label": { "type": "string", "description": "Label of the MCP server that provided the tool" }, "virtual_key_id": { "type": "string", "description": "ID of the virtual key used for this tool execution" }, "virtual_key_name": { "type": "string", "description": "Name of the virtual key used for this tool execution" }, "arguments": { "type": "object", "additionalProperties": true, "description": "Tool execution arguments" }, "result": { "type": "object", "additionalProperties": true, "description": "Tool execution result" }, "error_details": { "$ref": "#/components/schemas/BifrostError" }, "latency": { "type": "number", "description": "Execution time in milliseconds" }, "cost": { "type": "number", "description": "Cost in dollars for this tool execution" }, "status": { "type": "string", "enum": [ "processing", "success", "error" ], "description": "Execution status" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata captured from request headers (configured via logging_headers or x-bf-lh-* prefix)" }, "plugin_logs": { "type": "string", "description": "JSON-serialized plugin log entries grouped by plugin name" }, "redaction_mapping": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": { "type": "string" } }, "output": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Phase-scoped placeholder-to-original-value mappings for reversible MCP redactions. Present only on log detail responses when the caller has `Logs:Reveal`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the log entry was created" }, "virtual_key": { "type": "object", "additionalProperties": true, "description": "Full virtual key object (populated when virtual_key_id is set)" } } } }, "pagination": { "type": "object", "required": [ "total_count" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sort_by": { "type": "string" }, "order": { "type": "string" }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of items matching the query" } } }, "has_logs": { "type": "boolean", "description": "Whether any logs exist in the system" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteMCPLogs", "summary": "Delete MCP tool logs", "description": "Deletes MCP tool logs by their IDs.", "tags": [ "Logging" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delete MCP logs request", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Array of log IDs to delete" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP tool logs deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp-logs/{id}": { "get": { "operationId": "getMCPLogById", "summary": "Get MCP tool log by ID", "description": "Retrieves a single MCP tool execution log by ID, including hydrated object-storage payloads when configured.", "tags": [ "Logging" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP tool log ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP tool log found", "content": { "application/json": { "schema": { "type": "object", "description": "MCP tool execution log entry", "properties": { "id": { "type": "string", "description": "Unique identifier for the log entry" }, "llm_request_id": { "type": "string", "description": "Links to the LLM request that triggered this tool call" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the tool execution started" }, "tool_name": { "type": "string", "description": "Name of the MCP tool that was executed" }, "server_label": { "type": "string", "description": "Label of the MCP server that provided the tool" }, "virtual_key_id": { "type": "string", "description": "ID of the virtual key used for this tool execution" }, "virtual_key_name": { "type": "string", "description": "Name of the virtual key used for this tool execution" }, "arguments": { "type": "object", "additionalProperties": true, "description": "Tool execution arguments" }, "result": { "type": "object", "additionalProperties": true, "description": "Tool execution result" }, "error_details": { "$ref": "#/components/schemas/BifrostError" }, "latency": { "type": "number", "description": "Execution time in milliseconds" }, "cost": { "type": "number", "description": "Cost in dollars for this tool execution" }, "status": { "type": "string", "enum": [ "processing", "success", "error" ], "description": "Execution status" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata captured from request headers (configured via logging_headers or x-bf-lh-* prefix)" }, "plugin_logs": { "type": "string", "description": "JSON-serialized plugin log entries grouped by plugin name" }, "redaction_mapping": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": { "type": "string" } }, "output": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Phase-scoped placeholder-to-original-value mappings for reversible MCP redactions. Present only on log detail responses when the caller has `Logs:Reveal`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the log entry was created" }, "virtual_key": { "type": "object", "additionalProperties": true, "description": "Full virtual key object (populated when virtual_key_id is set)" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp-logs/stats": { "get": { "operationId": "getMCPLogsStats", "summary": "Get MCP tool log statistics", "description": "Returns statistics for MCP tool logs matching the specified filters.", "tags": [ "Logging" ], "parameters": [ { "name": "tool_names", "in": "query", "description": "Comma-separated list of tool names to filter by", "schema": { "type": "string" } }, { "name": "server_labels", "in": "query", "description": "Comma-separated list of server labels to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by", "schema": { "type": "string", "enum": [ "processing", "success", "error" ] } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "llm_request_ids", "in": "query", "description": "Comma-separated list of LLM request IDs to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter", "schema": { "type": "number" } }, { "name": "content_search", "in": "query", "description": "Search in tool arguments and results", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "MCP tool log statistics", "properties": { "total_executions": { "type": "integer", "description": "Total number of tool executions" }, "success_rate": { "type": "number", "description": "Success rate percentage" }, "average_latency": { "type": "number", "description": "Average execution latency in milliseconds" }, "total_cost": { "type": "number", "description": "Total cost in dollars for all executions" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp-logs/filterdata": { "get": { "operationId": "getMCPLogsFilterData", "summary": "Get available MCP log filter data", "description": "Returns all unique filter data from MCP tool logs (tool names, server labels).", "tags": [ "Logging" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Available MCP log filter data", "properties": { "tool_names": { "type": "array", "items": { "type": "string" }, "description": "All unique tool names" }, "server_labels": { "type": "array", "items": { "type": "string" }, "description": "All unique server labels" }, "virtual_keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Virtual key ID" }, "name": { "type": "string", "description": "Virtual key name" }, "value": { "type": "string", "description": "Virtual key value (redacted if applicable)" } } }, "description": "All unique virtual keys" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp-logs/histogram": { "get": { "operationId": "getMCPLogsHistogram", "summary": "Get MCP tool call volume histogram", "description": "Returns time-bucketed MCP tool call volume with success/error breakdown.", "tags": [ "Logging" ], "parameters": [ { "name": "tool_names", "in": "query", "description": "Comma-separated list of tool names to filter by", "schema": { "type": "string" } }, { "name": "server_labels", "in": "query", "description": "Comma-separated list of server labels to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by (processing, success, error)", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "llm_request_ids", "in": "query", "description": "Comma-separated list of LLM request IDs to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter (milliseconds)", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter (milliseconds)", "schema": { "type": "number" } }, { "name": "content_search", "in": "query", "description": "Search in tool arguments and results", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP histogram retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed MCP tool call volume histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed MCP tool call volume", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "format": "int64" }, "success": { "type": "integer", "format": "int64" }, "error": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp-logs/histogram/cost": { "get": { "operationId": "getMCPLogsCostHistogram", "summary": "Get MCP cost histogram", "description": "Returns time-bucketed MCP tool call cost data.", "tags": [ "Logging" ], "parameters": [ { "name": "tool_names", "in": "query", "description": "Comma-separated list of tool names to filter by", "schema": { "type": "string" } }, { "name": "server_labels", "in": "query", "description": "Comma-separated list of server labels to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by (processing, success, error)", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "llm_request_ids", "in": "query", "description": "Comma-separated list of LLM request IDs to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter (milliseconds)", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter (milliseconds)", "schema": { "type": "number" } }, { "name": "content_search", "in": "query", "description": "Search in tool arguments and results", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP cost histogram retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed MCP cost histogram", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "Time-bucketed MCP cost data", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total_cost": { "type": "number" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp-logs/histogram/top-tools": { "get": { "operationId": "getMCPLogsTopTools", "summary": "Get top MCP tools by call count", "description": "Returns the top 10 MCP tools by call count, with cost totals.", "tags": [ "Logging" ], "parameters": [ { "name": "tool_names", "in": "query", "description": "Comma-separated list of tool names to filter by", "schema": { "type": "string" } }, { "name": "server_labels", "in": "query", "description": "Comma-separated list of server labels to filter by", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Comma-separated list of statuses to filter by (processing, success, error)", "schema": { "type": "string" } }, { "name": "virtual_key_ids", "in": "query", "description": "Comma-separated list of virtual key IDs to filter by", "schema": { "type": "string" } }, { "name": "llm_request_ids", "in": "query", "description": "Comma-separated list of LLM request IDs to filter by", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Start time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "End time filter (RFC3339 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_latency", "in": "query", "description": "Minimum latency filter (milliseconds)", "schema": { "type": "number" } }, { "name": "max_latency", "in": "query", "description": "Maximum latency filter (milliseconds)", "schema": { "type": "number" } }, { "name": "content_search", "in": "query", "description": "Search in tool arguments and results", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "MCP top tools retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Top MCP tools by call count (limit 10)", "properties": { "tools": { "type": "array", "items": { "type": "object", "description": "Aggregated stats for a single MCP tool", "properties": { "tool_name": { "type": "string" }, "count": { "type": "integer", "format": "int64" }, "cost": { "type": "number" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/folders": { "get": { "operationId": "listFolders", "summary": "List folders", "description": "Returns all prompt folders.", "tags": [ "Prompt Repository" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "description": "Prompt folder", "properties": { "id": { "type": "string", "description": "Unique folder ID (UUID)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "prompts_count": { "type": "integer", "description": "Number of prompts in this folder (virtual field)" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createFolder", "summary": "Create folder", "description": "Creates a new prompt folder.", "tags": [ "Prompt Repository" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Folder created", "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "type": "object", "description": "Prompt folder", "properties": { "id": { "type": "string", "description": "Unique folder ID (UUID)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "prompts_count": { "type": "integer", "description": "Number of prompts in this folder (virtual field)" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/folders/{id}": { "get": { "operationId": "getFolder", "summary": "Get folder", "description": "Returns a folder by ID.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "type": "object", "description": "Prompt folder", "properties": { "id": { "type": "string", "description": "Unique folder ID (UUID)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "prompts_count": { "type": "integer", "description": "Number of prompts in this folder (virtual field)" } } } } } } } }, "404": { "description": "Folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateFolder", "summary": "Update folder", "description": "Updates a folder's name or description.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Folder updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "type": "object", "description": "Prompt folder", "properties": { "id": { "type": "string", "description": "Unique folder ID (UUID)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "prompts_count": { "type": "integer", "description": "Number of prompts in this folder (virtual field)" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteFolder", "summary": "Delete folder", "description": "Deletes a folder and cascades to contained prompts.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Folder deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/prompts": { "get": { "operationId": "listPrompts", "summary": "List prompts", "description": "Returns all prompts, optionally filtered by folder.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "folder_id", "in": "query", "description": "Filter by folder ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompts": { "type": "array", "items": { "type": "object", "description": "Prompt", "properties": { "id": { "type": "string", "description": "Unique prompt ID (UUID)" }, "name": { "type": "string" }, "folder_id": { "type": "string", "nullable": true }, "folder": { "type": "object", "description": "Prompt folder", "properties": { "id": { "type": "string", "description": "Unique folder ID (UUID)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "prompts_count": { "type": "integer", "description": "Number of prompts in this folder (virtual field)" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "versions": { "type": "array", "items": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } }, "sessions": { "type": "array", "items": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } }, "latest_version": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createPrompt", "summary": "Create prompt", "description": "Creates a new prompt.", "tags": [ "Prompt Repository" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "folder_id": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Prompt created", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "object", "description": "Prompt", "properties": { "id": { "type": "string", "description": "Unique prompt ID (UUID)" }, "name": { "type": "string" }, "folder_id": { "type": "string", "nullable": true }, "folder": { "type": "object", "description": "Prompt folder", "properties": { "id": { "type": "string", "description": "Unique folder ID (UUID)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "prompts_count": { "type": "integer", "description": "Number of prompts in this folder (virtual field)" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "versions": { "type": "array", "items": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } }, "sessions": { "type": "array", "items": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } }, "latest_version": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/prompts/{id}": { "get": { "operationId": "getPrompt", "summary": "Get prompt", "description": "Returns a prompt by ID with its latest version.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "object", "description": "Prompt", "properties": { "id": { "type": "string", "description": "Unique prompt ID (UUID)" }, "name": { "type": "string" }, "folder_id": { "type": "string", "nullable": true }, "folder": { "type": "object", "description": "Prompt folder", "properties": { "id": { "type": "string", "description": "Unique folder ID (UUID)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "prompts_count": { "type": "integer", "description": "Number of prompts in this folder (virtual field)" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "versions": { "type": "array", "items": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } }, "sessions": { "type": "array", "items": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } }, "latest_version": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } } } }, "404": { "description": "Prompt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updatePrompt", "summary": "Update prompt", "description": "Updates a prompt's name or folder.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "folder_id": { "type": "string", "nullable": true } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Prompt updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "object", "description": "Prompt", "properties": { "id": { "type": "string", "description": "Unique prompt ID (UUID)" }, "name": { "type": "string" }, "folder_id": { "type": "string", "nullable": true }, "folder": { "type": "object", "description": "Prompt folder", "properties": { "id": { "type": "string", "description": "Unique folder ID (UUID)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "prompts_count": { "type": "integer", "description": "Number of prompts in this folder (virtual field)" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "versions": { "type": "array", "items": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } }, "sessions": { "type": "array", "items": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } }, "latest_version": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deletePrompt", "summary": "Delete prompt", "description": "Deletes a prompt and all its versions and sessions.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Prompt deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Prompt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/prompts/{id}/versions": { "get": { "operationId": "listPromptVersions", "summary": "List prompt versions", "description": "Returns all versions for a prompt.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Prompt ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createPromptVersion", "summary": "Create prompt version", "description": "Creates a new version for a prompt.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Prompt ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "commit_message", "messages", "model_params", "provider", "model" ], "properties": { "commit_message": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Array of message objects" }, "model_params": { "type": "object", "additionalProperties": true }, "provider": { "type": "string" }, "model": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Version created", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/versions/{id}": { "get": { "operationId": "getPromptVersion", "summary": "Get prompt version", "description": "Returns a specific version by ID.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Version ID", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } }, "404": { "description": "Version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deletePromptVersion", "summary": "Delete prompt version", "description": "Deletes a specific version.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Version ID", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Version deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/prompts/{id}/sessions": { "get": { "operationId": "listPromptSessions", "summary": "List prompt sessions", "description": "Returns all sessions for a prompt.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Prompt ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createPromptSession", "summary": "Create prompt session", "description": "Creates a new playground session for a prompt.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Prompt ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "model_params", "provider", "model" ], "properties": { "name": { "type": "string" }, "version_id": { "type": "integer", "description": "Fork from this version" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "model_params": { "type": "object", "additionalProperties": true }, "provider": { "type": "string" }, "model": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/sessions/{id}": { "get": { "operationId": "getPromptSession", "summary": "Get prompt session", "description": "Returns a specific session by ID.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Session ID", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updatePromptSession", "summary": "Update prompt session", "description": "Updates a session's messages, model params, etc.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Session ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "messages", "model_params", "provider", "model" ], "properties": { "name": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "model_params": { "type": "object", "additionalProperties": true }, "provider": { "type": "string" }, "model": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Session updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deletePromptSession", "summary": "Delete prompt session", "description": "Deletes a specific session.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Session ID", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Session deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/sessions/{id}/rename": { "put": { "operationId": "renamePromptSession", "summary": "Rename prompt session", "description": "Renames a session.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Session ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Session renamed", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "description": "Prompt playground session", "properties": { "id": { "type": "integer", "description": "Auto-increment session ID" }, "prompt_id": { "type": "string" }, "version_id": { "type": "integer", "nullable": true, "description": "Version this session was forked from" }, "name": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt session", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/prompt-repo/sessions/{id}/commit": { "post": { "operationId": "commitPromptSession", "summary": "Commit session as version", "description": "Commits the current session state as a new prompt version.", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Session ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "commit_message" ], "properties": { "commit_message": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Version created from session", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "description": "Prompt version (immutable snapshot)", "properties": { "id": { "type": "integer", "description": "Auto-increment version ID" }, "prompt_id": { "type": "string" }, "version_number": { "type": "integer" }, "commit_message": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": true, "description": "Model parameters (flexible JSON object)" }, "provider": { "type": "string" }, "model": { "type": "string" }, "is_latest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "description": "Message within a prompt version", "properties": { "id": { "type": "integer" }, "order_index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "description": "Opaque message content (JSON)" } } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/files/upload": { "post": { "operationId": "uploadSkillFile", "summary": "Upload skill file", "description": "Uploads one file for later attachment to a skill version. The response contains either an object-storage key or a database blob ID.", "tags": [ "Skills" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadSkillFileRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSkillFileResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/files/orphans": { "delete": { "operationId": "cleanupOrphanSkillFiles", "summary": "Clean up orphan skill files", "description": "Deletes uploaded files that are not attached to any skill version. This is mostly a maintenance escape hatch: Bifrost also runs orphan cleanup on server startup. Non-forced cleanup preserves uploads newer than 24 hours so files are not deleted while a skill is still being edited.\n", "tags": [ "Skills" ], "parameters": [ { "name": "force", "in": "query", "description": "Bypass the 24-hour grace period when true.", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Cleanup completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillOrphanCleanupResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/all/version": { "get": { "operationId": "getAllSkillsVersion", "summary": "Get all-skills version", "description": "Returns the current version of the synthetic `bifrost-all-skills` marketplace plugin.", "tags": [ "Skills" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllSkillsVersionResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "bumpAllSkillsVersion", "summary": "Bump all-skills version", "description": "Manually bumps the synthetic `bifrost-all-skills` plugin version as an escape hatch for marketplace refreshes.", "tags": [ "Skills" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BumpAllSkillsVersionRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Version bumped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllSkillsVersionResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills": { "get": { "operationId": "listSkills", "summary": "List skills", "description": "Returns a paginated list of skills from the Skills Repository.", "tags": [ "Skills" ], "parameters": [ { "name": "search", "in": "query", "description": "Search by skill name or description.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Field to sort by.", "schema": { "type": "string", "enum": [ "name", "updated_at", "created_at" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "Sort order.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "description": "Number of skills to return. Maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "description": "Number of skills to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSkillsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "createSkill", "summary": "Create skill", "description": "Creates a new skill and immediately serves its first immutable version.", "tags": [ "Skills" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Skill created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/{id}": { "get": { "operationId": "getSkill", "summary": "Get skill", "description": "Returns a skill by ID. Pass `version` to inspect a historical version snapshot.", "tags": [ "Skills" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill ID", "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Optional version to load instead of the currently served version.", "schema": { "type": "string", "example": "1.0.0" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateSkill", "summary": "Update skill", "description": "Creates a new immutable skill version. Set `serve` to false to save the version without switching the served version.", "tags": [ "Skills" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Skill updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteSkill", "summary": "Delete skill", "description": "Deletes a skill and all of its versions.", "tags": [ "Skills" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Skill deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/{id}/versions": { "get": { "operationId": "listSkillVersions", "summary": "List skill versions", "description": "Returns immutable version snapshots for a skill.", "tags": [ "Skills" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill ID", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search versions by version string.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Field to sort by.", "schema": { "type": "string", "enum": [ "version", "created_at" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "Sort order.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "description": "Number of versions to return. Maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Number of versions to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSkillVersionsResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/{id}/shift-version": { "post": { "operationId": "shiftSkillVersion", "summary": "Shift served skill version", "description": "Changes the served version for a skill without deleting newer versions.", "tags": [ "Skills" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftSkillVersionRequest" } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Served version shifted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/serve/claude-code/.claude-plugin/marketplace.json": { "get": { "operationId": "getClaudeCodeSkillsMarketplace", "summary": "Get Claude Code skills marketplace", "description": "Public marketplace JSON consumed by Claude Code. Available only when the Bifrost server can access the `git` binary.", "tags": [ "Skills" ], "security": [], "responses": { "200": { "description": "Claude Code marketplace JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaudeCodeSkillMarketplace" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/serve/codex/.agents/plugins/marketplace.json": { "get": { "operationId": "getCodexSkillsMarketplace", "summary": "Get Codex skills marketplace JSON", "description": "Public Codex marketplace JSON for inspecting the skills and plugin sources exposed by Bifrost.", "tags": [ "Skills" ], "security": [], "responses": { "200": { "description": "Codex marketplace JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodexSkillMarketplace" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/serve/all/download.zip": { "get": { "operationId": "downloadAllSkills", "summary": "Download all skills as ZIP", "description": "Public ZIP download containing every currently served skill.", "tags": [ "Skills" ], "security": [], "responses": { "200": { "description": "ZIP archive", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/serve/{skill-name}/download.zip": { "get": { "operationId": "downloadSkill", "summary": "Download skill as ZIP", "description": "Public ZIP download containing a single currently served skill.", "tags": [ "Skills" ], "security": [], "parameters": [ { "name": "skill-name", "in": "path", "required": true, "description": "Skill name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ZIP archive", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/skills/serve/{skill-name}/files/{filepath}": { "get": { "operationId": "downloadSkillFile", "summary": "Download skill file", "description": "Public raw file download from the currently served version of a skill.", "tags": [ "Skills" ], "security": [], "parameters": [ { "name": "skill-name", "in": "path", "required": true, "description": "Skill name.", "schema": { "type": "string" } }, { "name": "filepath", "in": "path", "required": true, "description": "Relative file path inside the skill package.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw file content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/cache/clear/{cacheId}": { "delete": { "operationId": "clearCacheByCacheId", "summary": "Clear cache entry by cache ID", "description": "Deletes a single cache entry by its storage ID. Read the cache ID from\n`extra_fields.cache_debug.cache_id` on a prior response — it is populated\non both cache hits and cache misses.\n", "tags": [ "Cache" ], "parameters": [ { "name": "cacheId", "in": "path", "required": true, "description": "Storage ID of the cache entry to delete", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Cache cleared successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearCacheResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/cache/clear-by-key/{cacheKey}": { "delete": { "operationId": "clearCacheByCacheKey", "summary": "Clear cache by cache key", "description": "Clears a cache entry by its direct cache key.", "tags": [ "Cache" ], "parameters": [ { "name": "cacheKey", "in": "path", "required": true, "description": "Cache key to clear", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Cache cleared successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearCacheResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/vault/flush-cache": { "post": { "operationId": "flushVaultCache", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n" }, "summary": "Flush vault secret cache", "description": "Clears the in-memory vault secret cache so the next resolution of every\n`vault.` reference re-fetches from the configured backend (AWS Secrets\nManager, GCP Secret Manager, or HashiCorp Vault).\n\nUse this after rotating a secret when you cannot wait for the hourly\nbackground refresh. In a clustered deployment the flush is broadcast to all\npeer nodes automatically — you only need to call this on one node.\n\nReturns `400` if vault integration is not enabled.\n", "tags": [ "Vault" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Vault cache flushed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "vault cache flushed" } } } } } }, "400": { "description": "Vault is not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "vault is not enabled" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/ws": { "get": { "operationId": "websocketConnect", "summary": "WebSocket connection", "description": "Upgrades to a WebSocket connection for real-time updates.\nServer pushes log events, MCP log events, and store update notifications.\nHeartbeat pings are sent every 30 seconds.\n", "tags": [ "Infrastructure" ], "responses": { "101": { "description": "WebSocket upgrade successful" } } } }, "/mcp": { "post": { "operationId": "mcpServerMessage", "summary": "MCP protocol message", "description": "Receives a JSON-RPC 2.0 message for the MCP protocol server.\nReturns a JSON-RPC 2.0 response, or null for notifications.\n", "tags": [ "Infrastructure" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 request", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "method": { "type": "string" }, "params": { "type": "object" }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } } } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "mcpServerSSE", "summary": "MCP protocol SSE stream", "description": "Opens a Server-Sent Events stream for the MCP protocol server.\nReturns `Content-Type: text/event-stream`.\n", "tags": [ "Infrastructure" ], "responses": { "200": { "description": "SSE stream opened", "content": { "text/event-stream": { "schema": { "type": "string" } } } } }, "security": [ { "BearerAuth": [] }, { "BasicAuth": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/metrics": { "get": { "operationId": "getMetrics", "summary": "Prometheus metrics", "description": "Returns Prometheus-formatted metrics for monitoring.", "tags": [ "Infrastructure" ], "responses": { "200": { "description": "Prometheus metrics", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/api/webhooks": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Returns webhook endpoints, optionally filtered by search text, subscribed\nevent, and disabled status. Signing secrets are never included and custom\nheader values are redacted.\n", "tags": [ "Webhooks" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Case-insensitive match against endpoint name or URL.", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "Comma-separated events; returns endpoints subscribed to any of them.", "schema": { "type": "string" } }, { "name": "disabled", "in": "query", "required": false, "description": "Filter by disabled status. Omit for no filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A page of webhook endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "Creates a webhook endpoint. The signing secret is generated by the server\nand returned once in the response — it cannot be supplied and cannot be\nretrieved again afterwards.\n", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointRequest" } } } }, "responses": { "201": { "description": "Endpoint created; signing secret returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] } }, "/api/webhooks/{id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Get a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "responses": { "200": { "description": "The webhook endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] }, "put": { "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Updates a webhook endpoint. The signing secret is immutable here — use the\nrotate-secret endpoint to change it.\n", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointRequest" } } } }, "responses": { "200": { "description": "The updated webhook endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "responses": { "200": { "description": "Endpoint deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookStatusResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] } }, "/api/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookEndpointSecret", "summary": "Rotate a webhook signing secret", "description": "Generates a new signing secret for the endpoint and returns it once. The\nprevious secret stops verifying immediately — there is no grace window, so\nupdate your receiver in the same change.\n", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "responses": { "200": { "description": "Secret rotated; new signing secret returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] } }, "/api/webhooks/{id}/test": { "post": { "operationId": "testWebhookEndpoint", "summary": "Send a test delivery", "description": "Sends a sample signed delivery for the chosen event through the production\nsigning path.\n", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookRequest" } } } }, "responses": { "200": { "description": "Test delivery attempted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] } }, "/api/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List delivery history", "description": "Returns one page of delivery-attempt history for an endpoint, newest first.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A page of delivery history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Logs store is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] } }, "/api/webhooks/deliveries/{id}/redeliver": { "post": { "operationId": "redeliverWebhook", "summary": "Re-queue a delivery", "description": "Re-queues the delivery a history record belongs to, under its original\nwebhook-id so receivers can deduplicate the replay.\n", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The delivery history record id to re-queue.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Redelivery queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeliverWebhookResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "This delivery is already in flight.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] } }, "/api/notifications": { "get": { "operationId": "listNotifications", "summary": "List dashboard notifications", "description": "Returns notifications the caller is entitled to see, newest first.\nNotifications addressed to `all` are visible to everyone; those addressed\nto `roles` are only returned when the caller holds one of the listed\nroles. A local admin sees every notification.\n\nRead and dismissed state is not stored server-side, so every caller sees\nthe full page regardless of what they have already opened.\n", "tags": [ "Notifications" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Notifications per page. Values above the server page size of 50 are\nclamped down to it.\n", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` from a previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of notifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationList" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] }, "post": { "operationId": "createNotification", "summary": "Publish a dashboard notification", "description": "Persists a notification and pushes it over the dashboard WebSocket to\nevery connected client the audience covers.\n\nAdministrators only. Reading is open to any authenticated user because a\ncaller only ever receives rows their role already entitles them to, but a\nsingle publish reaches every dashboard user on the deployment, so it is\nrestricted to the local admin. On a deployment with dashboard auth\ndisabled every request is treated as local admin.\n\nNotifications expire 30 days after creation and are pruned hourly.\n", "tags": [ "Notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationInput" } } } }, "responses": { "201": { "description": "Notification published and broadcast", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "403": { "description": "Forbidden — authenticated, but not permitted to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token authentication. Use your provider API key or Bifrost authentication token.\nVirtual keys (prefixed with `sk-bf-`) can also be passed here.\n" }, "ManagementBearerAuth": { "type": "http", "scheme": "bearer", "description": "Management API authentication for `/api/*` endpoints. Use the `Authorization` header with `Bearer `.\nVirtual keys, dashboard/user/session tokens, and `x-api-key` headers are not supported on management APIs.\n" }, "BasicAuth": { "type": "http", "scheme": "basic", "description": "Basic authentication using username and password.\n" }, "VirtualKeyAuth": { "type": "apiKey", "in": "header", "name": "x-bf-vk", "description": "Bifrost Virtual Key for governance, routing, and access control. Supported on all inference endpoints (`/v1/*`, `/openai/*`, `/anthropic/*`, `/bedrock/*`, `/cohere/*`, `/genai/*`, `/langchain/*`, `/litellm/*`, `/pydanticai/*`, `/mcp`), not on management APIs (`/api/*`).\nExample: `sk-bf-*` prefixed keys.\n" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key authentication via the `x-api-key` header.\nVirtual keys (prefixed with `sk-bf-`) can also be passed here.\n" }, "SessionCookieAuth": { "type": "apiKey", "in": "cookie", "name": "token", "description": "Dashboard session authentication via the HTTPOnly `token` cookie that is\nset by `POST /api/session/login`. Used by the Bifrost UI for same-origin\nrequests in place of an `Authorization` header. Accepted on session\nendpoints (`logout`, `ws-ticket`) as an alternative to the management API key.\n" } }, "parameters": { "AsyncJobId": { "name": "job_id", "in": "path", "required": true, "description": "The unique identifier of the async job", "schema": { "type": "string" } }, "AsyncResultTTL": { "name": "x-bf-async-job-result-ttl", "in": "header", "required": false, "description": "Time-to-live in seconds for the job result after completion. Defaults to 3600 (1 hour).\nAfter expiry, the job result is automatically cleaned up.\n", "schema": { "type": "integer", "default": 3600 } }, "AsyncWebhookEndpoint": { "name": "x-bf-async-webhook", "in": "header", "required": false, "description": "Name of a registered webhook endpoint to notify when this job reaches a terminal\nstate (`completed` or `failed`). The endpoint must already exist and be enabled;\notherwise the submission is rejected with HTTP 400. If the endpoint is not subscribed\nto the resulting event, the job still completes normally but no delivery is enqueued.\nWhen omitted, no webhook is sent for the job and results are retrieved by polling.\nSee the Webhooks management API to register endpoints.\n", "schema": { "type": "string" } }, "WebhookEndpointId": { "name": "id", "in": "path", "required": true, "description": "The webhook endpoint id.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "Unauthorized": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "Forbidden": { "description": "Forbidden — authenticated, but not permitted to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "Conflict": { "description": "Conflict with the current state of the resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "ConfigStoreUnavailable": { "description": "Config store not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "schemas": { "ModelProvider": { "type": "string", "description": "AI model provider identifier", "enum": [ "openai", "azure", "anthropic", "bedrock", "cohere", "vertex", "vllm", "mistral", "ollama", "groq", "sgl", "parasail", "perplexity", "replicate", "cerebras", "deepseek", "gemini", "openrouter", "elevenlabs", "huggingface", "nebius", "xai", "runway", "fireworks" ] }, "Fallback": { "type": "object", "description": "Fallback model configuration", "required": [ "provider", "model" ], "properties": { "provider": { "$ref": "#/components/schemas/ModelProvider" }, "model": { "type": "string", "description": "Model name" } } }, "BifrostError": { "type": "object", "description": "Error response from Bifrost", "properties": { "event_id": { "type": "string" }, "type": { "type": "string" }, "is_bifrost_error": { "type": "boolean" }, "status_code": { "type": "integer" }, "error": { "$ref": "#/components/schemas/ErrorField" }, "extra_fields": { "$ref": "#/components/schemas/BifrostErrorExtraFields" } } }, "ErrorField": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "event_id": { "type": "string" } } }, "BifrostErrorExtraFields": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ModelProvider" }, "model_requested": { "type": "string" }, "request_type": { "type": "string" } } }, "BifrostResponseExtraFields": { "type": "object", "description": "Additional fields included in responses", "properties": { "request_type": { "type": "string", "description": "Type of request that was made" }, "provider": { "$ref": "#/components/schemas/ModelProvider" }, "model_requested": { "type": "string", "description": "The model that was requested" }, "model_deployment": { "type": "string", "description": "The actual model deployment used" }, "latency": { "type": "integer", "format": "int64", "description": "Request latency in milliseconds" }, "chunk_index": { "type": "integer", "description": "Index of the chunk for streaming responses" }, "raw_request": { "type": "object", "description": "Raw request if enabled" }, "raw_response": { "type": "object", "description": "Raw response if enabled" }, "cache_debug": { "$ref": "#/components/schemas/BifrostCacheDebug" } } }, "BifrostCacheDebug": { "type": "object", "properties": { "cache_hit": { "type": "boolean" }, "cache_id": { "type": "string" }, "hit_type": { "type": "string" }, "requested_provider": { "type": "string" }, "requested_model": { "type": "string" }, "provider_used": { "type": "string" }, "model_used": { "type": "string" }, "input_tokens": { "type": "integer" }, "threshold": { "type": "number" }, "similarity": { "type": "number" } } }, "CacheControl": { "type": "object", "description": "Cache control settings for content blocks", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "description": "Time to live (e.g., \"1m\", \"1h\")" } } }, "AsyncJobStatus": { "type": "string", "description": "The status of an async job", "enum": [ "pending", "processing", "completed", "failed" ] }, "AsyncJobResponse": { "type": "object", "description": "Response returned when creating or polling an async job", "required": [ "id", "status", "created_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the async job" }, "status": { "$ref": "#/components/schemas/AsyncJobStatus" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the job result expires and will be cleaned up" }, "created_at": { "type": "string", "format": "date-time", "description": "When the job was created" }, "completed_at": { "type": "string", "format": "date-time", "description": "When the job completed (successfully or with failure)" }, "status_code": { "type": "integer", "description": "HTTP status code of the completed operation" }, "result": { "description": "The result of the completed operation (shape depends on the request type)" }, "error": { "$ref": "#/components/schemas/BifrostError" } } }, "BifrostLLMUsage": { "type": "object", "description": "Token usage information", "properties": { "prompt_tokens": { "type": "integer", "description": "Total input tokens including any prompt-cache tokens (read + write). Subtract prompt_tokens_details.cached_read_tokens and prompt_tokens_details.cached_write_tokens to get the non-cached portion.\n" }, "prompt_tokens_details": { "$ref": "#/components/schemas/ChatPromptTokensDetails" }, "completion_tokens": { "type": "integer", "description": "Number of output/completion tokens generated." }, "completion_tokens_details": { "$ref": "#/components/schemas/ChatCompletionTokensDetails" }, "total_tokens": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/BifrostCost" } } }, "ChatPromptTokensDetails": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "image_tokens": { "type": "integer" }, "cached_read_tokens": { "type": "integer", "description": "Tokens served from the prompt cache (cache hit). These tokens are already included in prompt_tokens and are billed at the reduced cache-read rate. Populated for all providers that support prompt caching (Anthropic, Bedrock, OpenAI, Gemini, xAI, etc.).\n" }, "cached_write_tokens": { "type": "integer", "description": "Tokens written to the prompt cache on this request (cache creation / write). These tokens are already included in prompt_tokens and are billed at the cache-creation rate. Populated for providers that separately report cache write tokens (Anthropic, Bedrock).\n" } } }, "ChatCompletionTokensDetails": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "accepted_prediction_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "citation_tokens": { "type": "integer" }, "num_search_queries": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "image_tokens": { "type": "integer" }, "rejected_prediction_tokens": { "type": "integer" } } }, "BifrostCost": { "type": "object", "description": "Cost breakdown for the request", "properties": { "input_tokens_cost": { "type": "number" }, "output_tokens_cost": { "type": "number" }, "reasoning_tokens_cost": { "type": "number", "description": "Cost for reasoning/thinking tokens (reasoning models)" }, "citation_tokens_cost": { "type": "number", "description": "Cost for citation tokens" }, "search_queries_cost": { "type": "number", "description": "Cost for web search queries" }, "request_cost": { "type": "number" }, "total_cost": { "type": "number" } } }, "ListModelsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" }, "next_page_token": { "type": "string" } } }, "Model": { "type": "object", "properties": { "id": { "type": "string", "description": "Model ID in provider/model format" }, "canonical_slug": { "type": "string" }, "name": { "type": "string" }, "normalized_name": { "type": "string", "description": "Human-readable name derived from the Bifrost datasheet base model (e.g. \"Claude Sonnet 4.5\"). Only present when the model has a matching entry in the Bifrost pricing catalog." }, "deployment": { "type": "string" }, "created": { "type": "integer", "format": "int64" }, "context_length": { "type": "integer" }, "max_input_tokens": { "type": "integer" }, "max_output_tokens": { "type": "integer" }, "architecture": { "type": "object", "properties": { "modality": { "type": "string" }, "tokenizer": { "type": "string" }, "instruct_type": { "type": "string" }, "input_modalities": { "type": "array", "items": { "type": "string" } }, "output_modalities": { "type": "array", "items": { "type": "string" } } } }, "pricing": { "type": "object", "properties": { "prompt": { "type": "string" }, "completion": { "type": "string" }, "request": { "type": "string" }, "image": { "type": "string" }, "web_search": { "type": "string" }, "internal_reasoning": { "type": "string" }, "input_cache_read": { "type": "string" }, "input_cache_write": { "type": "string" } } }, "top_provider": { "type": "object", "properties": { "is_moderated": { "type": "boolean" }, "context_length": { "type": "integer" }, "max_completion_tokens": { "type": "integer" } } }, "per_request_limits": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" } } }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "default_parameters": { "type": "object", "properties": { "temperature": { "type": "number" }, "top_p": { "type": "number" }, "frequency_penalty": { "type": "number" } } }, "reasoning": { "type": "object", "description": "Reasoning capabilities advertised by the provider's list-models API (e.g. OpenRouter's per-model reasoning object). Fields are omitted when the provider does not report them; supported_efforts and default_effort are absent for models whose reasoning has no selectable effort level.", "properties": { "mandatory": { "type": "boolean" }, "default_enabled": { "type": "boolean" }, "supported_efforts": { "type": "array", "items": { "type": "string" } }, "default_effort": { "type": "string" } } }, "hugging_face_id": { "type": "string" }, "description": { "type": "string" }, "owned_by": { "type": "string" }, "supported_methods": { "type": "array", "items": { "type": "string" } } } }, "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format (e.g., openai/gpt-4)", "example": "openai/gpt-4" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "description": "List of messages in the conversation" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback models in provider/model format" }, "stream": { "type": "boolean", "description": "Whether to stream the response" }, "frequency_penalty": { "type": "number", "minimum": -2.0, "maximum": 2.0 }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number" } }, "logprobs": { "type": "boolean" }, "max_completion_tokens": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "modalities": { "type": "array", "items": { "type": "string" } }, "parallel_tool_calls": { "type": "boolean" }, "presence_penalty": { "type": "number", "minimum": -2.0, "maximum": 2.0 }, "prompt_cache_key": { "type": "string" }, "reasoning": { "type": "object", "properties": { "effort": { "type": "string", "description": "Reasoning effort level", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] }, "max_tokens": { "type": "integer" } } }, "response_format": { "type": "object", "description": "Format for the response" }, "safety_identifier": { "type": "string" }, "service_tier": { "type": "string" }, "stream_options": { "type": "object", "properties": { "include_obfuscation": { "type": "boolean" }, "include_usage": { "type": "boolean" } } }, "store": { "type": "boolean" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "none", "any", "required", "function", "allowed_tools", "custom" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ] }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } } } } } } ] }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "custom" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true }, "enum": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } } }, "strict": { "type": "boolean" } } }, "custom": { "type": "object", "properties": { "format": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "grammar": { "type": "object", "required": [ "definition", "syntax" ], "properties": { "definition": { "type": "string" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ] } } } } } } }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, "seed": { "type": "integer", "description": "Deterministic sampling seed" }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "description": "Nucleus sampling parameter" }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Number of most likely tokens to return at each position" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Up to 4 sequences where the API will stop generating tokens" }, "prediction": { "type": "object", "description": "Predicted output content for the model to reference (OpenAI only). Can reduce latency.", "properties": { "type": { "type": "string", "description": "Always \"content\"" }, "content": { "description": "Predicted content (string or array of content parts)", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] } } }, "prompt_cache_retention": { "type": "string", "enum": [ "in_memory", "24h" ], "description": "Prompt cache retention policy" }, "web_search_options": { "type": "object", "description": "Web search options for chat completions (OpenAI only)", "properties": { "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Amount of search context to include" }, "user_location": { "type": "object", "properties": { "type": { "type": "string", "description": "Location type (e.g., \"approximate\")" }, "approximate": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string", "description": "Two-letter ISO country code (e.g., \"US\")" }, "region": { "type": "string", "description": "Region or state (e.g., \"California\")" }, "timezone": { "type": "string", "description": "IANA timezone (e.g., \"America/Los_Angeles\")" } } } } } } }, "truncation": { "type": "string" }, "user": { "type": "string" }, "verbosity": { "type": "string", "enum": [ "low", "medium", "high" ] } } }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "created": { "type": "integer" }, "model": { "type": "string" }, "object": { "type": "string" }, "service_tier": { "type": "string" }, "system_fingerprint": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" }, "search_results": { "type": "array", "items": { "$ref": "#/components/schemas/PerplexitySearchResult" } }, "videos": { "type": "array", "items": { "$ref": "#/components/schemas/PerplexityVideoResult" } }, "citations": { "type": "array", "items": { "type": "string" } } } }, "ChatMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "assistant", "user", "system", "tool", "developer" ] }, "name": { "type": "string" }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "input_audio", "file", "refusal" ] }, "text": { "type": "string" }, "refusal": { "type": "string" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "low", "high", "auto" ] } } }, "input_audio": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string" }, "format": { "type": "string" } } }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" } } }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ], "description": "Message content - can be a string or array of content blocks" }, "tool_call_id": { "type": "string", "description": "For tool messages" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url_citation": { "type": "object", "properties": { "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "sources": { "type": "object" }, "type": { "type": "string" } } } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } } }, "PerplexitySearchResult": { "type": "object", "description": "Search result from Perplexity AI search", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "date": { "type": "string" }, "last_updated": { "type": "string" }, "snippet": { "type": "string" }, "source": { "type": "string" } } }, "PerplexityVideoResult": { "type": "object", "properties": { "url": { "type": "string" }, "thumbnail_url": { "type": "string" }, "thumbnail_width": { "type": "integer" }, "thumbnail_height": { "type": "integer" }, "duration": { "type": "number" } } }, "TextCompletionRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format" }, "prompt": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Prompt input - can be a string or array of strings" }, "fallbacks": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "best_of": { "type": "integer" }, "echo": { "type": "boolean" }, "frequency_penalty": { "type": "number" }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number" } }, "logprobs": { "type": "integer" }, "max_tokens": { "type": "integer" }, "n": { "type": "integer" }, "presence_penalty": { "type": "number" }, "seed": { "type": "integer" }, "stop": { "type": "array", "items": { "type": "string" } }, "suffix": { "type": "string" }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "user": { "type": "string" } } }, "TextCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "finish_reason": { "type": "string" }, "log_probs": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } }, "text_offset": { "type": "array", "items": { "type": "integer" } }, "token_logprobs": { "type": "array", "items": { "type": "number" } }, "tokens": { "type": "array", "items": { "type": "string" } }, "top_logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "text": { "type": "string", "description": "For text completions" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "For non-streaming chat completions" }, "delta": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "refusal": { "type": "string" }, "audio": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "string" }, "expires_at": { "type": "integer" }, "transcript": { "type": "string" } } }, "reasoning": { "type": "string" }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "type": { "type": "string", "enum": [ "reasoning.summary", "reasoning.encrypted", "reasoning.text" ] }, "summary": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "description": "For streaming chat completions" } } } }, "model": { "type": "string" }, "object": { "type": "string" }, "system_fingerprint": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "ContextManagement": { "description": "Automatic context window management. The wire shape depends on the target provider: OpenAI-compatible providers accept an array of {type, compact_threshold} entries; Anthropic-compatible providers accept an object with an \"edits\" array (compact_20260112, clear_tool_uses_20250919, clear_thinking_20251015).\n", "oneOf": [ { "type": "array", "description": "OpenAI native shape — an array of context-management entries.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Entry type. Currently only \"compaction\" is supported." }, "compact_threshold": { "type": "integer", "description": "Token threshold at which compaction should be triggered for this entry." } }, "additionalProperties": true } }, { "type": "object", "description": "Anthropic native shape — an object with an \"edits\" array.", "properties": { "edits": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } ] }, "ResponsesRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } } ], "description": "Input - can be a string or array of messages" }, "fallbacks": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "background": { "type": "boolean" }, "conversation": { "type": "string" }, "context_management": { "$ref": "#/components/schemas/ContextManagement" }, "include": { "type": "array", "items": { "type": "string" } }, "instructions": { "type": "string" }, "max_output_tokens": { "type": "integer" }, "max_tool_calls": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "parallel_tool_calls": { "type": "boolean" }, "previous_response_id": { "type": "string" }, "prompt_cache_key": { "type": "string" }, "reasoning": { "type": "object", "properties": { "effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] }, "generate_summary": { "type": "string", "deprecated": true }, "summary": { "type": "string", "enum": [ "auto", "concise", "detailed" ] }, "max_tokens": { "type": "integer" } } }, "safety_identifier": { "type": "string" }, "service_tier": { "type": "string" }, "stream_options": { "type": "object", "properties": { "include_obfuscation": { "type": "boolean" } } }, "store": { "type": "boolean" }, "temperature": { "type": "number" }, "text": { "type": "object", "properties": { "format": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "json_schema", "json_object" ] }, "name": { "type": "string" }, "schema": { "type": "object" }, "strict": { "type": "boolean" } } }, "verbosity": { "type": "string", "enum": [ "low", "medium", "high" ] } } }, "top_logprobs": { "type": "integer" }, "top_p": { "type": "number" }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "none", "auto", "any", "required", "function", "allowed_tools", "file_search", "web_search_preview", "computer_use_preview", "code_interpreter", "image_generation", "mcp", "custom" ] }, "mode": { "type": "string" }, "name": { "type": "string" }, "server_label": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "mcp", "image_generation" ] }, "name": { "type": "string" }, "server_label": { "type": "string" } } } } } } ] }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "file_search", "computer_use_preview", "web_search", "web_fetch", "mcp", "code_interpreter", "image_generation", "local_shell", "custom", "web_search_preview", "memory", "tool_search" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true }, "enum": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } } }, "strict": { "type": "boolean" }, "vector_store_ids": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object" }, "max_num_results": { "type": "integer" }, "ranking_options": { "type": "object" }, "display_height": { "type": "integer" }, "display_width": { "type": "integer" }, "environment": { "type": "string" }, "enable_zoom": { "type": "boolean" }, "search_context_size": { "type": "string" }, "user_location": { "type": "object" }, "server_label": { "type": "string" }, "server_url": { "type": "string" }, "allowed_tools": { "type": "object" }, "authorization": { "type": "string" }, "connector_id": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "require_approval": { "type": "object" }, "server_description": { "type": "string" }, "container": { "type": "object" }, "background": { "type": "string" }, "input_fidelity": { "type": "string" }, "input_image_mask": { "type": "object" }, "moderation": { "type": "string" }, "output_compression": { "type": "integer" }, "output_format": { "type": "string" }, "partial_images": { "type": "integer" }, "quality": { "type": "string" }, "size": { "type": "string" }, "format": { "type": "object" } } } }, "truncation": { "type": "string" } } }, "ResponsesResponse": { "type": "object", "properties": { "id": { "type": "string" }, "background": { "type": "boolean" }, "conversation": { "type": "object" }, "created_at": { "type": "integer" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "include": { "type": "array", "items": { "type": "string" } }, "incomplete_details": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } }, "instructions": { "type": "object" }, "max_output_tokens": { "type": "integer" }, "max_tool_calls": { "type": "integer" }, "metadata": { "type": "object" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } }, "parallel_tool_calls": { "type": "boolean" }, "previous_response_id": { "type": "string" }, "prompt": { "type": "object" }, "prompt_cache_key": { "type": "string" }, "reasoning": { "type": "object", "properties": { "effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] }, "generate_summary": { "type": "string", "deprecated": true }, "summary": { "type": "string", "enum": [ "auto", "concise", "detailed" ] }, "max_tokens": { "type": "integer" } } }, "safety_identifier": { "type": "string" }, "service_tier": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "failed", "in_progress", "canceled", "queued", "incomplete" ] }, "stop_reason": { "type": "string" }, "store": { "type": "boolean" }, "temperature": { "type": "number" }, "text": { "type": "object", "properties": { "format": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "json_schema", "json_object" ] }, "name": { "type": "string" }, "schema": { "type": "object" }, "strict": { "type": "boolean" } } }, "verbosity": { "type": "string", "enum": [ "low", "medium", "high" ] } } }, "top_logprobs": { "type": "integer" }, "top_p": { "type": "number" }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "none", "auto", "any", "required", "function", "allowed_tools", "file_search", "web_search_preview", "computer_use_preview", "code_interpreter", "image_generation", "mcp", "custom" ] }, "mode": { "type": "string" }, "name": { "type": "string" }, "server_label": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "mcp", "image_generation" ] }, "name": { "type": "string" }, "server_label": { "type": "string" } } } } } } ] }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "file_search", "computer_use_preview", "web_search", "web_fetch", "mcp", "code_interpreter", "image_generation", "local_shell", "custom", "web_search_preview", "memory", "tool_search" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true }, "enum": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } } }, "strict": { "type": "boolean" }, "vector_store_ids": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object" }, "max_num_results": { "type": "integer" }, "ranking_options": { "type": "object" }, "display_height": { "type": "integer" }, "display_width": { "type": "integer" }, "environment": { "type": "string" }, "enable_zoom": { "type": "boolean" }, "search_context_size": { "type": "string" }, "user_location": { "type": "object" }, "server_label": { "type": "string" }, "server_url": { "type": "string" }, "allowed_tools": { "type": "object" }, "authorization": { "type": "string" }, "connector_id": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "require_approval": { "type": "object" }, "server_description": { "type": "string" }, "container": { "type": "object" }, "background": { "type": "string" }, "input_fidelity": { "type": "string" }, "input_image_mask": { "type": "object" }, "moderation": { "type": "string" }, "output_compression": { "type": "integer" }, "output_format": { "type": "string" }, "partial_images": { "type": "integer" }, "quality": { "type": "string" }, "size": { "type": "string" }, "format": { "type": "object" } } } }, "truncation": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "input_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "image_tokens": { "type": "integer" }, "cached_read_tokens": { "type": "integer", "description": "Tokens served from the prompt cache (cache hit), billed at the reduced cache-read rate. Already included in the parent input_tokens total.\n" }, "cached_write_tokens": { "type": "integer", "description": "Tokens written to the prompt cache on this request, billed at the cache-creation rate. Already included in the parent input_tokens total. Populated for providers that separately report cache write tokens (Anthropic, Bedrock).\n" } } }, "output_tokens": { "type": "integer" }, "output_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "accepted_prediction_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "rejected_prediction_tokens": { "type": "integer" }, "citation_tokens": { "type": "integer" }, "num_search_queries": { "type": "integer" } } }, "total_tokens": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/BifrostCost" } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" }, "search_results": { "type": "array", "items": { "$ref": "#/components/schemas/PerplexitySearchResult" } }, "videos": { "type": "array", "items": { "$ref": "#/components/schemas/PerplexityVideoResult" } }, "citations": { "type": "array", "items": { "type": "string" } } } }, "BifrostResponsesDeleteResponse": { "type": "object", "description": "Wire shape for a successful delete of a stored response.", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "BifrostResponsesInputItemsResponse": { "type": "object", "description": "List payload for a response's input items.", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } }, "has_more": { "type": "boolean" }, "first_id": { "type": "string" }, "last_id": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "RerankRequest": { "type": "object", "required": [ "model", "query", "documents" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format", "example": "cohere/rerank-v3.5" }, "query": { "type": "string", "minLength": 1, "description": "Query used to score and reorder documents" }, "documents": { "type": "array", "description": "Documents to rerank", "minItems": 1, "items": { "$ref": "#/components/schemas/RerankDocument" } }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback models in provider/model format" }, "top_n": { "type": "integer", "minimum": 1, "description": "Maximum number of ranked results to return" }, "max_tokens_per_doc": { "type": "integer", "minimum": 1, "description": "Maximum tokens to consider per document (provider-dependent)" }, "priority": { "type": "integer", "description": "Request priority hint (provider-dependent)" }, "return_documents": { "type": "boolean", "description": "Whether to include document content in each result" } } }, "RerankResponse": { "type": "object", "required": [ "results", "model" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the rerank response" }, "results": { "type": "array", "description": "Ranked results ordered by relevance score descending", "items": { "$ref": "#/components/schemas/RerankResult" } }, "model": { "type": "string", "description": "Model used to perform reranking" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "RerankDocument": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "description": "Document text content" }, "id": { "type": "string", "minLength": 1, "description": "Optional document identifier" }, "meta": { "type": "object", "description": "Optional document metadata", "additionalProperties": true } } }, "RerankResult": { "type": "object", "required": [ "index", "relevance_score" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Index into the original documents array" }, "relevance_score": { "type": "number", "description": "Relevance score for this document" }, "document": { "$ref": "#/components/schemas/RerankDocument" } } }, "EmbeddingRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "integer" } }, { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } } ], "description": "Input for embedding - text or token arrays" }, "fallbacks": { "type": "array", "items": { "type": "string" } }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] }, "dimensions": { "type": "integer" } } }, "EmbeddingResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "object": { "type": "string" }, "embedding": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "number" } }, { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } ] } } } }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "SpeechRequest": { "type": "object", "required": [ "model", "input", "voice" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format" }, "input": { "type": "string", "description": "Text to convert to speech" }, "fallbacks": { "type": "array", "items": { "type": "string" } }, "stream_format": { "type": "string", "enum": [ "sse" ], "description": "Set to \"sse\" to enable streaming" }, "voice": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "speaker", "voice" ], "properties": { "speaker": { "type": "string" }, "voice": { "type": "string" } } } } ] }, "instructions": { "type": "string" }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4.0 }, "language_code": { "type": "string" }, "pronunciation_dictionary_locators": { "type": "array", "items": { "type": "object", "required": [ "pronunciation_dictionary_id" ], "properties": { "pronunciation_dictionary_id": { "type": "string" }, "version_id": { "type": "string" } } } }, "enable_logging": { "type": "boolean" }, "optimize_streaming_latency": { "type": "boolean" }, "with_timestamps": { "type": "boolean" } } }, "SpeechResponse": { "type": "object", "properties": { "audio": { "type": "string", "format": "byte", "description": "Audio data (binary)" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "alignment": { "type": "object", "properties": { "char_start_times_ms": { "type": "array", "items": { "type": "number" } }, "char_end_times_ms": { "type": "array", "items": { "type": "number" } }, "characters": { "type": "array", "items": { "type": "string" } } } }, "normalized_alignment": { "type": "object", "properties": { "char_start_times_ms": { "type": "array", "items": { "type": "number" } }, "char_end_times_ms": { "type": "array", "items": { "type": "number" } }, "characters": { "type": "array", "items": { "type": "string" } } } }, "audio_base64": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "TranscriptionRequest": { "type": "object", "required": [ "model", "file" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format" }, "file": { "type": "string", "format": "binary", "description": "Audio file to transcribe" }, "fallbacks": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "language": { "type": "string" }, "prompt": { "type": "string" }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt" ] }, "file_format": { "type": "string" } } }, "TranscriptionResponse": { "type": "object", "properties": { "duration": { "type": "number" }, "language": { "type": "string" }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "type": "array", "items": { "type": "integer" } } } } }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "seek": { "type": "integer" }, "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "integer" } }, "temperature": { "type": "number" }, "avg_logprob": { "type": "number" }, "compression_ratio": { "type": "number" }, "no_speech_prob": { "type": "number" } } } }, "task": { "type": "string" }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tokens", "duration" ] }, "input_tokens": { "type": "integer" }, "input_token_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "seconds": { "type": "integer" } } }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "start": { "type": "number" }, "end": { "type": "number" } } } }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "CountTokensRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } }, "fallbacks": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "file_search", "computer_use_preview", "web_search", "web_fetch", "mcp", "code_interpreter", "image_generation", "local_shell", "custom", "web_search_preview", "memory", "tool_search" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true }, "enum": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } } }, "strict": { "type": "boolean" }, "vector_store_ids": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object" }, "max_num_results": { "type": "integer" }, "ranking_options": { "type": "object" }, "display_height": { "type": "integer" }, "display_width": { "type": "integer" }, "environment": { "type": "string" }, "enable_zoom": { "type": "boolean" }, "search_context_size": { "type": "string" }, "user_location": { "type": "object" }, "server_label": { "type": "string" }, "server_url": { "type": "string" }, "allowed_tools": { "type": "object" }, "authorization": { "type": "string" }, "connector_id": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "require_approval": { "type": "object" }, "server_description": { "type": "string" }, "container": { "type": "object" }, "background": { "type": "string" }, "input_fidelity": { "type": "string" }, "input_image_mask": { "type": "object" }, "moderation": { "type": "string" }, "output_compression": { "type": "integer" }, "output_format": { "type": "string" }, "partial_images": { "type": "integer" }, "quality": { "type": "string" }, "size": { "type": "string" }, "format": { "type": "object" } } } }, "instructions": { "type": "string" }, "text": { "type": "string" } } }, "CountTokensResponse": { "type": "object", "properties": { "object": { "type": "string" }, "model": { "type": "string" }, "input_tokens": { "type": "integer" }, "input_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "image_tokens": { "type": "integer" }, "cached_read_tokens": { "type": "integer", "description": "Tokens served from the prompt cache (cache hit), billed at the reduced cache-read rate. Already included in the parent input_tokens total.\n" }, "cached_write_tokens": { "type": "integer", "description": "Tokens written to the prompt cache on this request, billed at the cache-creation rate. Already included in the parent input_tokens total. Populated for providers that separately report cache write tokens (Anthropic, Bedrock).\n" } } }, "tokens": { "type": "array", "items": { "type": "integer" } }, "token_strings": { "type": "array", "items": { "type": "string" } }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "BatchCreateRequest": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format" }, "input_file_id": { "type": "string", "description": "OpenAI-style file ID" }, "requests": { "type": "array", "items": { "type": "object", "required": [ "custom_id" ], "properties": { "custom_id": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "body": { "type": "object" }, "params": { "type": "object" } } }, "description": "Anthropic-style inline requests" }, "endpoint": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/embeddings", "/v1/completions", "/v1/responses", "/v1/messages" ] }, "completion_window": { "type": "string", "description": "e.g., \"24h\"" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "BatchCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "endpoint": { "type": "string" }, "input_file_id": { "type": "string" }, "completion_window": { "type": "string" }, "status": { "type": "string", "enum": [ "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "canceled", "ended" ] }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "succeeded": { "type": "integer" }, "expired": { "type": "integer" }, "canceled": { "type": "integer" }, "pending": { "type": "integer" } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "created_at": { "type": "integer", "format": "int64" }, "expires_at": { "type": "integer", "format": "int64" }, "output_file_id": { "type": "string" }, "error_file_id": { "type": "string" }, "processing_status": { "type": "string" }, "results_url": { "type": "string" }, "operation_name": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "BatchListResponse": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchRetrieveResponse" } }, "first_id": { "type": "string" }, "last_id": { "type": "string" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "BatchRetrieveResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "endpoint": { "type": "string" }, "input_file_id": { "type": "string" }, "completion_window": { "type": "string" }, "status": { "type": "string", "enum": [ "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "canceled", "ended" ] }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "succeeded": { "type": "integer" }, "expired": { "type": "integer" }, "canceled": { "type": "integer" }, "pending": { "type": "integer" } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "created_at": { "type": "integer", "format": "int64" }, "expires_at": { "type": "integer", "format": "int64" }, "in_progress_at": { "type": "integer", "format": "int64" }, "finalizing_at": { "type": "integer", "format": "int64" }, "completed_at": { "type": "integer", "format": "int64" }, "failed_at": { "type": "integer", "format": "int64" }, "expired_at": { "type": "integer", "format": "int64" }, "cancelling_at": { "type": "integer", "format": "int64" }, "cancelled_at": { "type": "integer", "format": "int64" }, "output_file_id": { "type": "string" }, "error_file_id": { "type": "string" }, "errors": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "line": { "type": "integer" } } } } } }, "processing_status": { "type": "string" }, "results_url": { "type": "string" }, "archived_at": { "type": "integer", "format": "int64" }, "operation_name": { "type": "string" }, "done": { "type": "boolean" }, "progress": { "type": "integer" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "FileUploadRequest": { "type": "object", "required": [ "file", "purpose" ], "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "type": "string", "enum": [ "batch", "assistants", "fine-tune", "vision", "batch_output", "user_data", "responses", "evals" ] }, "provider": { "$ref": "#/components/schemas/ModelProvider" } } }, "FileUploadResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "integer", "format": "int64" }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "batch", "assistants", "fine-tune", "vision", "batch_output", "user_data", "responses", "evals" ] }, "status": { "type": "string", "enum": [ "uploaded", "processed", "processing", "error", "deleted" ] }, "status_details": { "type": "string" }, "expires_at": { "type": "integer", "format": "int64" }, "storage_backend": { "type": "string" }, "storage_uri": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "FileListResponse": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "integer", "format": "int64" }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "batch", "assistants", "fine-tune", "vision", "batch_output", "user_data", "responses", "evals" ] }, "status": { "type": "string", "enum": [ "uploaded", "processed", "processing", "error", "deleted" ] }, "status_details": { "type": "string" }, "expires_at": { "type": "integer", "format": "int64" } } } }, "has_more": { "type": "boolean" }, "after": { "type": "string" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "OCRRequest": { "type": "object", "required": [ "model", "document" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format", "example": "mistral/mistral-ocr-latest" }, "id": { "type": "string", "description": "Optional unique identifier for the request" }, "document": { "$ref": "#/components/schemas/OCRDocument" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback models in provider/model format" }, "include_image_base64": { "type": "boolean", "description": "Whether to include base64-encoded images in the response" }, "pages": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Specific page indices to process (0-based)" }, "image_limit": { "type": "integer", "minimum": 1, "description": "Maximum number of images to extract per page" }, "image_min_size": { "type": "integer", "minimum": 1, "description": "Minimum image size in pixels to extract" }, "table_format": { "type": "string", "description": "Format for extracted tables (e.g., \"markdown\", \"html\")" }, "extract_header": { "type": "boolean", "description": "Whether to extract page headers" }, "extract_footer": { "type": "boolean", "description": "Whether to extract page footers" }, "confidence_scores_granularity": { "type": "string", "enum": [ "page", "block", "word", "document" ], "description": "Granularity of confidence scores to include in the response" }, "bbox_annotation_format": { "type": "object", "description": "Format for bounding box annotations. Supports text, json_object, and json_schema modes.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ], "description": "The format type" }, "json_schema": { "type": "object", "description": "JSON schema definition (required when type is json_schema)", "properties": { "schema": { "type": "object", "description": "The JSON schema" }, "name": { "type": "string", "description": "Name of the schema" }, "strict": { "type": "boolean", "description": "Whether to enforce strict validation" } } } }, "oneOf": [ { "properties": { "type": { "enum": [ "text", "json_object" ] } } }, { "required": [ "type", "json_schema" ], "properties": { "type": { "enum": [ "json_schema" ] } } } ] }, "document_annotation_format": { "type": "object", "description": "Format for document-level annotations. Supports text, json_object, and json_schema modes.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ], "description": "The format type" }, "json_schema": { "type": "object", "description": "JSON schema definition (required when type is json_schema)", "properties": { "schema": { "type": "object", "description": "The JSON schema" }, "name": { "type": "string", "description": "Name of the schema" }, "strict": { "type": "boolean", "description": "Whether to enforce strict validation" } } } }, "oneOf": [ { "properties": { "type": { "enum": [ "text", "json_object" ] } } }, { "required": [ "type", "json_schema" ], "properties": { "type": { "enum": [ "json_schema" ] } } } ] }, "document_annotation_prompt": { "type": "string", "description": "Custom prompt for document annotation" } } }, "OCRDocument": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document_url", "image_url" ], "description": "Type of document input:\n- `document_url`: A PDF URL or base64 data URL\n- `image_url`: An image URL\n" }, "document_url": { "type": "string", "description": "URL or base64 data URL of the document (required when type is document_url)" }, "image_url": { "type": "string", "description": "URL of the image to process (required when type is image_url)" } }, "oneOf": [ { "required": [ "type", "document_url" ], "properties": { "type": { "enum": [ "document_url" ] } } }, { "required": [ "type", "image_url" ], "properties": { "type": { "enum": [ "image_url" ] } } } ] }, "OCRResponse": { "type": "object", "required": [ "model", "pages" ], "properties": { "model": { "type": "string", "description": "Model used to perform OCR" }, "pages": { "type": "array", "description": "Processed pages with extracted content", "items": { "$ref": "#/components/schemas/OCRPage" } }, "usage_info": { "$ref": "#/components/schemas/OCRUsageInfo" }, "document_annotation": { "type": "string", "description": "Document-level annotation if requested" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "OCRPage": { "type": "object", "required": [ "index", "markdown" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Zero-based page index" }, "markdown": { "type": "string", "description": "Extracted text content in Markdown format" }, "images": { "type": "array", "description": "Images extracted from this page", "items": { "$ref": "#/components/schemas/OCRPageImage" } }, "dimensions": { "$ref": "#/components/schemas/OCRPageDimensions" }, "tables": { "type": "array", "description": "Tables extracted from this page (present when table_format is set)", "nullable": true, "items": { "type": "object" } }, "header": { "type": "string", "nullable": true, "description": "Header content extracted from this page (present when extract_header is true)" }, "footer": { "type": "string", "nullable": true, "description": "Footer content extracted from this page (present when extract_footer is true)" }, "confidence_scores": { "type": "object", "nullable": true, "description": "Confidence scores for this page (present when confidence_scores_granularity is set)", "properties": { "average_page_confidence_score": { "type": "number", "description": "Average confidence score for the page" }, "minimum_page_confidence_score": { "type": "number", "description": "Minimum confidence score for the page" }, "word_confidence_scores": { "type": "array", "description": "Per-word confidence scores", "items": { "type": "number" } } } } } }, "OCRPageImage": { "type": "object", "required": [ "id", "top_left_x", "top_left_y", "bottom_right_x", "bottom_right_y" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the image within the page" }, "top_left_x": { "type": "number", "description": "X coordinate of the top-left corner of the image bounding box" }, "top_left_y": { "type": "number", "description": "Y coordinate of the top-left corner of the image bounding box" }, "bottom_right_x": { "type": "number", "description": "X coordinate of the bottom-right corner of the image bounding box" }, "bottom_right_y": { "type": "number", "description": "Y coordinate of the bottom-right corner of the image bounding box" }, "image_base64": { "type": "string", "description": "Base64-encoded image data (present when include_image_base64 is true)" } } }, "OCRPageDimensions": { "type": "object", "required": [ "dpi", "height", "width" ], "properties": { "dpi": { "type": "integer", "description": "Dots per inch of the page" }, "height": { "type": "integer", "description": "Page height in pixels" }, "width": { "type": "integer", "description": "Page width in pixels" } } }, "OCRUsageInfo": { "type": "object", "required": [ "pages_processed", "doc_size_bytes" ], "properties": { "pages_processed": { "type": "integer", "description": "Number of pages processed" }, "doc_size_bytes": { "type": "integer", "description": "Size of the processed document in bytes" } } }, "OpenAIChatRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Model identifier (e.g., gpt-4, gpt-3.5-turbo)", "example": "gpt-4" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/OpenAIMessage" }, "description": "List of messages in the conversation" }, "stream": { "type": "boolean", "description": "Whether to stream the response" }, "max_tokens": { "type": "integer", "description": "Maximum tokens to generate (legacy, use max_completion_tokens)" }, "max_completion_tokens": { "type": "integer", "description": "Maximum tokens to generate" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number" }, "frequency_penalty": { "type": "number", "minimum": -2.0, "maximum": 2.0 }, "presence_penalty": { "type": "number", "minimum": -2.0, "maximum": 2.0 }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number" } }, "logprobs": { "type": "boolean" }, "top_logprobs": { "type": "integer" }, "n": { "type": "integer" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "seed": { "type": "integer" }, "user": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "custom" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true }, "enum": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } } }, "strict": { "type": "boolean" } } }, "custom": { "type": "object", "properties": { "format": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "grammar": { "type": "object", "required": [ "definition", "syntax" ], "properties": { "definition": { "type": "string" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ] } } } } } } }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "none", "any", "required", "function", "allowed_tools", "custom" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ] }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } } } } } } ] }, "parallel_tool_calls": { "type": "boolean" }, "response_format": { "type": "object", "description": "Format for the response" }, "reasoning_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ], "description": "OpenAI reasoning effort level" }, "service_tier": { "type": "string" }, "stream_options": { "type": "object", "properties": { "include_obfuscation": { "type": "boolean" }, "include_usage": { "type": "boolean" } } }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback models" } } }, "OpenAIMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool", "developer" ] }, "name": { "type": "string" }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "input_audio", "file", "refusal" ] }, "text": { "type": "string" }, "refusal": { "type": "string" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "low", "high", "auto" ] } } }, "input_audio": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string" }, "format": { "type": "string" } } }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" } } }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ], "description": "Message content - can be a string or array of content blocks" }, "tool_call_id": { "type": "string", "description": "For tool messages" }, "refusal": { "type": "string" }, "reasoning": { "type": "string" }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url_citation": { "type": "object", "properties": { "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "sources": { "type": "object" }, "type": { "type": "string" } } } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } } }, "OpenAITextCompletionRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model identifier", "example": "gpt-3.5-turbo-instruct" }, "prompt": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "The prompt(s) to generate completions for" }, "stream": { "type": "boolean", "description": "Whether to stream the response" }, "max_tokens": { "type": "integer" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number" }, "frequency_penalty": { "type": "number", "minimum": -2.0, "maximum": 2.0 }, "presence_penalty": { "type": "number", "minimum": -2.0, "maximum": 2.0 }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number" } }, "logprobs": { "type": "integer" }, "n": { "type": "integer" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "suffix": { "type": "string" }, "echo": { "type": "boolean" }, "best_of": { "type": "integer" }, "user": { "type": "string" }, "seed": { "type": "integer" }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "OpenAIResponsesRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model identifier", "example": "gpt-4" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } } ], "description": "Input - can be a string or array of messages" }, "stream": { "type": "boolean" }, "context_management": { "$ref": "#/components/schemas/ContextManagement" }, "instructions": { "type": "string", "description": "System instructions for the model" }, "max_output_tokens": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "parallel_tool_calls": { "type": "boolean" }, "previous_response_id": { "type": "string" }, "reasoning": { "type": "object", "properties": { "effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] }, "generate_summary": { "type": "string", "enum": [ "auto", "concise", "detailed" ] }, "summary": { "type": "string", "enum": [ "auto", "concise", "detailed" ] }, "max_tokens": { "type": "integer" } } }, "store": { "type": "boolean" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "text": { "type": "object", "properties": { "format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "schema": { "type": "object" }, "strict": { "type": "boolean" } } } } } } }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "none", "auto", "any", "required", "function", "allowed_tools", "file_search", "web_search_preview", "computer_use_preview", "code_interpreter", "image_generation", "mcp", "custom" ] }, "mode": { "type": "string" }, "name": { "type": "string" }, "server_label": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "mcp", "image_generation" ] }, "name": { "type": "string" }, "server_label": { "type": "string" } } } } } } ] }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "file_search", "computer_use_preview", "web_search", "web_fetch", "mcp", "code_interpreter", "image_generation", "local_shell", "custom", "web_search_preview", "memory", "tool_search" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true }, "enum": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } } }, "strict": { "type": "boolean" }, "vector_store_ids": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object" }, "max_num_results": { "type": "integer" }, "ranking_options": { "type": "object" }, "display_height": { "type": "integer" }, "display_width": { "type": "integer" }, "environment": { "type": "string" }, "enable_zoom": { "type": "boolean" }, "search_context_size": { "type": "string" }, "user_location": { "type": "object" }, "server_label": { "type": "string" }, "server_url": { "type": "string" }, "allowed_tools": { "type": "object" }, "authorization": { "type": "string" }, "connector_id": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "require_approval": { "type": "object" }, "server_description": { "type": "string" }, "container": { "type": "object" }, "background": { "type": "string" }, "input_fidelity": { "type": "string" }, "input_image_mask": { "type": "object" }, "moderation": { "type": "string" }, "output_compression": { "type": "integer" }, "output_format": { "type": "string" }, "partial_images": { "type": "integer" }, "quality": { "type": "string" }, "size": { "type": "string" }, "format": { "type": "object" } } } }, "top_p": { "type": "number" }, "truncation": { "type": "string", "enum": [ "auto", "disabled" ] }, "user": { "type": "string" }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "OpenAIEmbeddingRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model identifier", "example": "text-embedding-3-small" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Input text to embed" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] }, "dimensions": { "type": "integer", "description": "Number of dimensions for the embedding" }, "user": { "type": "string" }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "OpenAISpeechRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model identifier (e.g., tts-1, tts-1-hd)", "example": "tts-1" }, "input": { "type": "string", "description": "Text to convert to speech" }, "voice": { "type": "string", "description": "Voice to use", "enum": [ "alloy", "echo", "fable", "onyx", "nova", "shimmer" ] }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4.0 }, "stream_format": { "type": "string", "enum": [ "sse" ], "description": "Set to 'sse' for streaming" }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "OpenAITranscriptionRequest": { "type": "object", "required": [ "model", "file" ], "properties": { "model": { "type": "string", "description": "Model identifier (e.g., whisper-1)", "example": "whisper-1" }, "file": { "type": "string", "format": "binary", "description": "Audio file to transcribe" }, "language": { "type": "string", "description": "Language of the audio (ISO 639-1)" }, "prompt": { "type": "string", "description": "Prompt to guide transcription" }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "timestamp_granularities": { "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "stream": { "type": "boolean" }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "OpenAIListModelsResponse": { "type": "object", "properties": { "object": { "type": "string", "default": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Model identifier" }, "object": { "type": "string", "default": "model" }, "owned_by": { "type": "string" }, "created": { "type": "integer", "format": "int64" }, "active": { "type": "boolean", "description": "GROQ-specific field" }, "context_window": { "type": "integer", "description": "GROQ-specific field" } } } } } }, "AnthropicMessageRequest": { "type": "object", "required": [ "model", "max_tokens", "messages" ], "properties": { "model": { "type": "string", "description": "Model identifier (e.g., claude-3-opus-20240229)", "example": "claude-3-opus-20240229" }, "max_tokens": { "type": "integer", "description": "Maximum tokens to generate" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicMessage" }, "description": "List of messages in the conversation" }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicContentBlock" } } ], "description": "System prompt" }, "cache_control": { "$ref": "#/components/schemas/CacheControl", "description": "Automatic caching directives for the whole request" }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string" } } }, "stream": { "type": "boolean", "description": "Whether to stream the response" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom", "bash_20250124", "computer_20250124", "computer_20251124", "code_execution_20250522", "code_execution_20250825", "code_execution_20260120", "text_editor_20250124", "text_editor_20250429", "text_editor_20250728", "web_search_20250305", "web_search_20260209", "web_fetch_20250910", "web_fetch_20260209", "web_fetch_20260309", "memory_20250818", "tool_search_tool_bm25", "tool_search_tool_bm25_20251119", "tool_search_tool_regex", "tool_search_tool_regex_20251119" ] }, "name": { "type": "string", "description": "Tool name (for custom tools)" }, "description": { "type": "string" }, "input_schema": { "type": "object", "description": "JSON Schema for tool input" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" }, "display_width_px": { "type": "integer" }, "display_height_px": { "type": "integer" }, "display_number": { "type": "integer" }, "enable_zoom": { "type": "boolean" }, "max_uses": { "type": "integer" }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "blocked_domains": { "type": "array", "items": { "type": "string" } }, "user_location": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "approximate" ] }, "city": { "type": "string" }, "country": { "type": "string" }, "timezone": { "type": "string" } } } } } }, "tool_choice": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto", "any", "tool", "none" ] }, "name": { "type": "string", "description": "Required when type is 'tool'" }, "disable_parallel_tool_use": { "type": "boolean" } } } ] }, "mcp_servers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "authorization_token": { "type": "string", "description": "Authorization token for the MCP server" }, "tool_configuration": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "allowed_tools": { "type": "array", "items": { "type": "string" } } } } } }, "description": "MCP servers configuration (requires beta header)" }, "thinking": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled" ] }, "budget_tokens": { "type": "integer" } } }, "output_format": { "type": "object", "description": "Structured output format (requires beta header)" }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "AnthropicMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicContentBlock" } } ], "description": "Content - can be a string or array of content blocks" } } }, "AnthropicContentBlock": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image", "document", "tool_use", "server_tool_use", "tool_result", "web_search_result", "mcp_tool_use", "mcp_tool_result", "thinking", "redacted_thinking" ] }, "text": { "type": "string", "description": "For text content" }, "thinking": { "type": "string", "description": "For thinking content" }, "signature": { "type": "string", "description": "For signature content" }, "data": { "type": "string", "description": "For data content (encrypted data for redacted thinking)" }, "tool_use_id": { "type": "string", "description": "For tool_result content" }, "id": { "type": "string", "description": "For tool_use content" }, "name": { "type": "string", "description": "For tool_use content" }, "input": { "type": "object", "description": "For tool_use content" }, "server_name": { "type": "string", "description": "For mcp_tool_use content" }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicContentBlock" } } ], "description": "For tool_result content" }, "source": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "base64", "url", "text", "content_block" ] }, "media_type": { "type": "string", "description": "MIME type (e.g., image/jpeg, application/pdf)" }, "data": { "type": "string", "description": "Base64-encoded data (for base64 type)" }, "url": { "type": "string", "description": "URL (for url type)" } }, "description": "For image/document content" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" }, "citations": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "For document content" }, "context": { "type": "string", "description": "For document content" }, "title": { "type": "string", "description": "For document content" } } }, "AnthropicMessageResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "default": "message" }, "role": { "type": "string", "default": "assistant" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicContentBlock" } }, "model": { "type": "string" }, "stop_reason": { "type": "string", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "refusal", "model_context_window_exceeded", null ] }, "stop_sequence": { "type": "string", "nullable": true }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" }, "cache_creation": { "type": "object", "properties": { "ephemeral_5m_input_tokens": { "type": "integer" }, "ephemeral_1h_input_tokens": { "type": "integer" } } } } } } }, "AnthropicTextRequest": { "type": "object", "required": [ "model", "prompt", "max_tokens_to_sample" ], "properties": { "model": { "type": "string", "description": "Model identifier" }, "prompt": { "type": "string", "description": "The prompt to complete" }, "max_tokens_to_sample": { "type": "integer", "description": "Maximum tokens to generate" }, "stream": { "type": "boolean" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "AnthropicListModelsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Model identifier" }, "type": { "type": "string", "default": "model" }, "display_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "first_id": { "type": "string" }, "last_id": { "type": "string" } } }, "GeminiSchema": { "type": "object", "description": "Schema object for defining input/output data types (OpenAPI 3.0 subset)", "properties": { "type": { "type": "string", "enum": [ "TYPE_UNSPECIFIED", "STRING", "NUMBER", "INTEGER", "BOOLEAN", "ARRAY", "OBJECT", "NULL" ], "description": "The type of the data" }, "format": { "type": "string", "description": "Format of the data (e.g., float, double, int32, int64, email, byte)" }, "title": { "type": "string", "description": "The title of the Schema" }, "description": { "type": "string", "description": "The description of the data" }, "nullable": { "type": "boolean", "description": "Indicates if the value may be null" }, "enum": { "type": "array", "items": { "type": "string" }, "description": "Possible values for primitive types with enum format" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/GeminiSchema" }, "description": "Properties of Type.OBJECT" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Required properties of Type.OBJECT" }, "items": { "$ref": "#/components/schemas/GeminiSchema", "description": "Schema of the elements of Type.ARRAY" }, "minItems": { "type": "integer", "description": "Minimum number of elements for Type.ARRAY" }, "maxItems": { "type": "integer", "description": "Maximum number of elements for Type.ARRAY" }, "minLength": { "type": "integer", "description": "Minimum length of Type.STRING" }, "maxLength": { "type": "integer", "description": "Maximum length of Type.STRING" }, "minimum": { "type": "number", "description": "Minimum value of Type.INTEGER and Type.NUMBER" }, "maximum": { "type": "number", "description": "Maximum value of Type.INTEGER and Type.NUMBER" }, "pattern": { "type": "string", "description": "Pattern to restrict a string to a regular expression" }, "default": { "description": "Default value of the data" }, "example": { "description": "Example of the object (only populated when object is root)" }, "anyOf": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiSchema" }, "description": "Value should be validated against any of the subschemas" }, "propertyOrdering": { "type": "array", "items": { "type": "string" }, "description": "Order of the properties (not standard OpenAPI)" }, "minProperties": { "type": "integer", "description": "Minimum number of properties for Type.OBJECT" }, "maxProperties": { "type": "integer", "description": "Maximum number of properties for Type.OBJECT" } } }, "GeminiGenerationRequest": { "type": "object", "properties": { "model": { "type": "string", "description": "Model field for explicit model specification" }, "contents": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiContent" }, "description": "Content for the model to process" }, "systemInstruction": { "$ref": "#/components/schemas/GeminiContent", "description": "System instruction for the model" }, "generationConfig": { "type": "object", "properties": { "temperature": { "type": "number", "description": "Controls the randomness of predictions" }, "topP": { "type": "number", "description": "Nucleus sampling parameter" }, "topK": { "type": "integer", "description": "Top-k sampling parameter" }, "candidateCount": { "type": "integer", "description": "Number of candidates to generate. Defaults to 1" }, "maxOutputTokens": { "type": "integer", "description": "Maximum number of output tokens to generate per message" }, "stopSequences": { "type": "array", "items": { "type": "string" }, "description": "Stop sequences" }, "responseMimeType": { "type": "string", "description": "Output response mimetype (text/plain, application/json)" }, "responseSchema": { "$ref": "#/components/schemas/GeminiSchema", "description": "Schema for JSON response (OpenAPI 3.0 subset)" }, "responseJsonSchema": { "type": "object", "description": "Alternative to responseSchema using JSON Schema format" }, "responseModalities": { "type": "array", "items": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ] }, "description": "The modalities of the response" }, "speechConfig": { "type": "object", "properties": { "voiceConfig": { "type": "object", "properties": { "prebuiltVoiceConfig": { "type": "object", "properties": { "voiceName": { "type": "string", "description": "The name of the prebuilt voice to use" } } } } }, "multiSpeakerVoiceConfig": { "type": "object", "properties": { "speakerVoiceConfigs": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "string", "description": "The name of the speaker (should match prompt)" }, "voiceConfig": { "type": "object", "properties": { "prebuiltVoiceConfig": { "type": "object", "properties": { "voiceName": { "type": "string", "description": "The name of the prebuilt voice to use" } } } } } } } } } }, "languageCode": { "type": "string", "description": "Language code (ISO 639) for speech synthesis. Only available for Live API" } } }, "thinkingConfig": { "type": "object", "properties": { "includeThoughts": { "type": "boolean", "description": "Whether to include thoughts in the response" }, "thinkingBudget": { "type": "integer", "description": "Thinking budget in tokens" }, "thinkingLevel": { "type": "string", "enum": [ "THINKING_LEVEL_UNSPECIFIED", "LOW", "HIGH" ], "description": "Thinking level preset" } } }, "frequencyPenalty": { "type": "number", "description": "Frequency penalty for token generation" }, "presencePenalty": { "type": "number", "description": "Presence penalty for token generation" }, "seed": { "type": "integer", "description": "Seed for deterministic generation" }, "logprobs": { "type": "integer", "description": "Number of log probabilities to return" }, "responseLogprobs": { "type": "boolean", "description": "If true, export logprobs results in response" }, "audioTimestamp": { "type": "boolean", "description": "If enabled, audio timestamp will be included in request" }, "mediaResolution": { "type": "string", "description": "Media resolution specification" }, "routingConfig": { "type": "object", "properties": { "autoMode": { "type": "object", "properties": { "modelRoutingPreference": { "type": "string", "description": "Model routing preference" } } }, "manualMode": { "type": "object", "properties": { "modelName": { "type": "string", "description": "Model name to use" } } } } }, "modelSelectionConfig": { "type": "object", "properties": { "featureSelectionPreference": { "type": "string", "description": "Options for feature selection preference" } } }, "enableAffectiveDialog": { "type": "boolean", "description": "If enabled, model will detect emotions and adapt responses" } } }, "safetySettings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Harm category" }, "threshold": { "type": "string", "description": "The harm block threshold" }, "method": { "type": "string", "description": "Determines if harm block uses probability or probability and severity scores" } } } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Function name. Must start with letter/underscore, a-z, A-Z, 0-9, underscores, dots, dashes. Max 64 chars" }, "description": { "type": "string", "description": "Description and purpose of the function" }, "parameters": { "$ref": "#/components/schemas/GeminiSchema" }, "parametersJsonSchema": { "type": "object", "description": "Alternative to parameters using JSON Schema format" }, "response": { "$ref": "#/components/schemas/GeminiSchema", "description": "Output schema for the function" }, "responseJsonSchema": { "type": "object", "description": "Alternative to response using JSON Schema format" }, "behavior": { "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ], "description": "Function behavior mode. BLOCKING waits for response, NON_BLOCKING continues conversation" } } } }, "googleSearch": { "type": "object", "properties": { "timeRangeFilter": { "type": "object", "properties": { "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" } } }, "excludeDomains": { "type": "array", "items": { "type": "string" }, "description": "List of domains to exclude from search results (max 2000)" } } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "description": "The mode of the predictor for dynamic retrieval" }, "dynamicThreshold": { "type": "number", "description": "Threshold for dynamic retrieval" } } } } }, "retrieval": { "type": "object", "properties": { "disableAttribution": { "type": "boolean", "deprecated": true, "description": "Deprecated. This option is no longer supported" }, "externalApi": { "type": "object", "properties": { "endpoint": { "type": "string", "description": "The endpoint of the external API" }, "apiSpec": { "type": "string", "enum": [ "API_SPEC_UNSPECIFIED", "SIMPLE_SEARCH", "ELASTIC_SEARCH" ] }, "authConfig": { "type": "object", "properties": { "authType": { "type": "string", "enum": [ "AUTH_TYPE_UNSPECIFIED", "NO_AUTH", "API_KEY_AUTH", "HTTP_BASIC_AUTH", "GOOGLE_SERVICE_ACCOUNT_AUTH", "OAUTH", "OIDC_AUTH" ] }, "apiKeyConfig": { "type": "object", "properties": { "apiKeyString": { "type": "string" } } }, "googleServiceAccountConfig": { "type": "object", "properties": { "serviceAccount": { "type": "string" } } }, "httpBasicAuthConfig": { "type": "object", "properties": { "credentialSecret": { "type": "string" } } }, "oauthConfig": { "type": "object", "properties": { "accessToken": { "type": "string" }, "serviceAccount": { "type": "string" } } }, "oidcConfig": { "type": "object", "properties": { "idToken": { "type": "string" }, "serviceAccount": { "type": "string" } } } } }, "elasticSearchParams": { "type": "object", "properties": { "index": { "type": "string", "description": "The ElasticSearch index to use" }, "numHits": { "type": "integer", "description": "Number of hits (chunks) to request" }, "searchTemplate": { "type": "string", "description": "The ElasticSearch search template to use" } } } } }, "vertexAiSearch": { "type": "object", "properties": { "datastore": { "type": "string", "description": "Fully-qualified Vertex AI Search data store resource ID" }, "engine": { "type": "string", "description": "Fully-qualified Vertex AI Search engine resource ID" }, "filter": { "type": "string", "description": "Filter strings to be passed to the search API" }, "maxResults": { "type": "integer", "description": "Number of search results to return (max 10, default 10)" }, "dataStoreSpecs": { "type": "array", "items": { "type": "object", "properties": { "dataStore": { "type": "string", "description": "Full resource name of DataStore" }, "filter": { "type": "string", "description": "Filter specification for documents in the data store" } } } } } }, "vertexRagStore": { "type": "object", "properties": { "ragCorpora": { "type": "array", "items": { "type": "string" }, "deprecated": true, "description": "Deprecated. Use ragResources instead" }, "ragResources": { "type": "array", "items": { "type": "object", "properties": { "ragCorpus": { "type": "string", "description": "RAGCorpora resource name" }, "ragFileIds": { "type": "array", "items": { "type": "string" }, "description": "rag_file_id. Files should be in the same rag_corpus" } } } }, "ragRetrievalConfig": { "type": "object", "properties": { "topK": { "type": "integer", "description": "The number of contexts to retrieve" }, "filter": { "type": "object", "properties": { "metadataFilter": { "type": "string", "description": "String for metadata filtering" }, "vectorDistanceThreshold": { "type": "number", "description": "Only returns contexts with vector distance smaller than threshold" }, "vectorSimilarityThreshold": { "type": "number", "description": "Only returns contexts with vector similarity larger than threshold" } } }, "hybridSearch": { "type": "object", "properties": { "alpha": { "type": "number", "description": "Weight between dense and sparse vector search (0-1). 0 = sparse only, 1 = dense only" } } }, "ranking": { "type": "object", "properties": { "llmRanker": { "type": "object", "properties": { "modelName": { "type": "string" } } }, "rankService": { "type": "object", "properties": { "modelName": { "type": "string" } } } } } } }, "similarityTopK": { "type": "integer", "description": "Number of top k results to return from selected corpora" }, "storeContext": { "type": "boolean", "description": "For Gemini Multimodal Live API - memorize interactions" }, "vectorDistanceThreshold": { "type": "number", "description": "Only return results with vector distance smaller than threshold" } } } } }, "codeExecution": { "type": "object", "description": "Enables code execution by the model" }, "enterpriseWebSearch": { "type": "object", "properties": { "excludeDomains": { "type": "array", "items": { "type": "string" }, "description": "List of domains to exclude (max 2000)" } } }, "googleMaps": { "type": "object", "properties": { "authConfig": { "type": "object", "properties": { "authType": { "type": "string", "enum": [ "AUTH_TYPE_UNSPECIFIED", "NO_AUTH", "API_KEY_AUTH", "HTTP_BASIC_AUTH", "GOOGLE_SERVICE_ACCOUNT_AUTH", "OAUTH", "OIDC_AUTH" ] }, "apiKeyConfig": { "type": "object", "properties": { "apiKeyString": { "type": "string" } } }, "googleServiceAccountConfig": { "type": "object", "properties": { "serviceAccount": { "type": "string" } } }, "httpBasicAuthConfig": { "type": "object", "properties": { "credentialSecret": { "type": "string" } } }, "oauthConfig": { "type": "object", "properties": { "accessToken": { "type": "string" }, "serviceAccount": { "type": "string" } } }, "oidcConfig": { "type": "object", "properties": { "idToken": { "type": "string" }, "serviceAccount": { "type": "string" } } } } } } }, "urlContext": { "type": "object", "description": "Tool to support URL context retrieval" }, "computerUse": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "ENVIRONMENT_UNSPECIFIED", "ENVIRONMENT_BROWSER" ], "description": "The environment being operated" } } } } } }, "toolConfig": { "type": "object", "properties": { "functionCallingConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "AUTO", "ANY", "NONE", "VALIDATED" ], "description": "Function calling mode" }, "allowedFunctionNames": { "type": "array", "items": { "type": "string" }, "description": "Function names to call when mode is ANY" } } }, "retrievalConfig": { "type": "object", "properties": { "latLng": { "type": "object", "properties": { "latitude": { "type": "number", "description": "Latitude in degrees [-90.0, +90.0]" }, "longitude": { "type": "number", "description": "Longitude in degrees [-180.0, +180.0]" } } }, "languageCode": { "type": "string" } } } } }, "cachedContent": { "type": "string", "description": "Cached content resource name" }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Labels for the request" }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiEmbeddingRequest" }, "description": "Batch embedding requests" }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "GeminiGenerationResponse": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/GeminiContent" }, "finishReason": { "type": "string", "enum": [ "FINISH_REASON_UNSPECIFIED", "STOP", "MAX_TOKENS", "SAFETY", "RECITATION", "LANGUAGE", "OTHER", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII", "MALFORMED_FUNCTION_CALL", "IMAGE_SAFETY", "UNEXPECTED_TOOL_CALL" ] }, "finishMessage": { "type": "string", "description": "Human-readable finish message" }, "tokenCount": { "type": "integer", "description": "Number of tokens for this candidate" }, "safetyRatings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Harm category" }, "probability": { "type": "string", "description": "Harm probability level" }, "probabilityScore": { "type": "number", "description": "Harm probability score" }, "severity": { "type": "string", "description": "Harm severity level" }, "severityScore": { "type": "number", "description": "Harm severity score" }, "blocked": { "type": "boolean", "description": "Whether content was filtered" }, "overwrittenThreshold": { "type": "string", "description": "Overwritten threshold for safety category (for Gemini 2.0 image output with minors detected)" } } } }, "citationMetadata": { "type": "object", "description": "Source attribution of the generated content" }, "index": { "type": "integer", "description": "Index of the candidate" }, "groundingMetadata": { "type": "object", "description": "Metadata specifying sources used to ground generated content" }, "urlContextMetadata": { "type": "object", "properties": { "urlMetadata": { "type": "array", "items": { "type": "object", "properties": { "retrievedUrl": { "type": "string" }, "urlRetrievalStatus": { "type": "string" } } } } } }, "avgLogprobs": { "type": "number", "description": "Average log probability score of the candidate" }, "logprobsResult": { "type": "object", "properties": { "chosenCandidates": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "The candidate's token string value" }, "tokenId": { "type": "integer", "description": "The candidate's token ID value" }, "logProbability": { "type": "number", "description": "The candidate's log probability" } } } }, "topCandidates": { "type": "array", "items": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "The candidate's token string value" }, "tokenId": { "type": "integer", "description": "The candidate's token ID value" }, "logProbability": { "type": "number", "description": "The candidate's log probability" } } } } } } } } } } } }, "promptFeedback": { "type": "object", "properties": { "blockReason": { "type": "string" }, "blockReasonMessage": { "type": "string", "description": "Human-readable block reason message" }, "safetyRatings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Harm category" }, "probability": { "type": "string", "description": "Harm probability level" }, "probabilityScore": { "type": "number", "description": "Harm probability score" }, "severity": { "type": "string", "description": "Harm severity level" }, "severityScore": { "type": "number", "description": "Harm severity score" }, "blocked": { "type": "boolean", "description": "Whether content was filtered" }, "overwrittenThreshold": { "type": "string", "description": "Overwritten threshold for safety category (for Gemini 2.0 image output with minors detected)" } } } } } }, "usageMetadata": { "type": "object", "properties": { "promptTokenCount": { "type": "integer", "description": "Number of tokens in the prompt (includes cached content)" }, "candidatesTokenCount": { "type": "integer", "description": "Number of tokens in the response(s)" }, "totalTokenCount": { "type": "integer", "description": "Total token count for prompt, response candidates, and tool-use prompts" }, "cachedContentTokenCount": { "type": "integer", "description": "Number of tokens in the cached part of the input" }, "thoughtsTokenCount": { "type": "integer", "description": "Number of tokens in thoughts output" }, "toolUsePromptTokenCount": { "type": "integer", "description": "Number of tokens in tool-use prompts" }, "trafficType": { "type": "string", "description": "Traffic type (Pay-As-You-Go or Provisioned Throughput)" }, "cacheTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "description": "The modality (TEXT, IMAGE, AUDIO, etc.)" }, "tokenCount": { "type": "integer" } } }, "description": "Modalities of the cached content in the request input" }, "candidatesTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "description": "The modality (TEXT, IMAGE, AUDIO, etc.)" }, "tokenCount": { "type": "integer" } } }, "description": "Modalities returned in the response" }, "promptTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "description": "The modality (TEXT, IMAGE, AUDIO, etc.)" }, "tokenCount": { "type": "integer" } } }, "description": "Modalities processed in the request input" }, "toolUsePromptTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "description": "The modality (TEXT, IMAGE, AUDIO, etc.)" }, "tokenCount": { "type": "integer" } } }, "description": "Modalities processed for tool-use request inputs" } } }, "modelVersion": { "type": "string", "description": "The model version used to generate the response" }, "responseId": { "type": "string", "description": "Response ID for identifying each response (encoding of event_id)" }, "createTime": { "type": "string", "format": "date-time", "description": "Timestamp when the request was made to the server" } } }, "GeminiContent": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "model" ], "description": "The producer of the content. Must be either 'user' or 'model'" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiPart" }, "description": "List of parts that constitute a single message" } } }, "GeminiPart": { "type": "object", "properties": { "text": { "type": "string", "description": "Text part (can be code)" }, "thought": { "type": "boolean", "description": "Indicates if the part is thought from the model" }, "thoughtSignature": { "type": "string", "format": "byte", "description": "Opaque signature for thought that can be reused in subsequent requests" }, "inlineData": { "type": "object", "properties": { "mimeType": { "type": "string", "description": "The IANA standard MIME type of the source data" }, "data": { "type": "string", "format": "byte", "description": "Base64-encoded raw bytes" }, "displayName": { "type": "string", "description": "Display name of the blob (not currently used in GenerateContent calls)" } } }, "fileData": { "type": "object", "properties": { "mimeType": { "type": "string", "description": "The IANA standard MIME type of the source data" }, "fileUri": { "type": "string", "description": "URI of the file" }, "displayName": { "type": "string", "description": "Display name of the file data" } } }, "functionCall": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the function call. If populated, client should return response with matching id" }, "name": { "type": "string", "description": "The name of the function to call. Matches FunctionDeclaration.name" }, "args": { "type": "object", "description": "Function parameters and values in JSON object format" } } }, "functionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the function call this response is for. Matches FunctionCall.id" }, "name": { "type": "string", "description": "The name of the function. Matches FunctionDeclaration.name and FunctionCall.name" }, "response": { "type": "object", "description": "Function response in JSON object format. Use \"output\" key for output and \"error\" key for error details" }, "willContinue": { "type": "boolean", "description": "Signals that function call continues (NON_BLOCKING only). If false, future responses will not be considered" }, "scheduling": { "type": "string", "description": "How the response should be scheduled (NON_BLOCKING only). Defaults to WHEN_IDLE" } } }, "executableCode": { "type": "object", "properties": { "language": { "type": "string", "description": "Programming language of the code" }, "code": { "type": "string", "description": "The code to be executed" } } }, "codeExecutionResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "OUTCOME_UNSPECIFIED", "OUTCOME_OK", "OUTCOME_FAILED", "OUTCOME_DEADLINE_EXCEEDED" ], "description": "Outcome of the code execution" }, "output": { "type": "string", "description": "Contains stdout when successful, stderr or other description otherwise" } } }, "videoMetadata": { "type": "object", "properties": { "fps": { "type": "number", "description": "Frame rate of the video. Range is (0.0, 24.0]" }, "startOffset": { "type": "string", "description": "Start offset of the video" }, "endOffset": { "type": "string", "description": "End offset of the video" } } } } }, "GeminiEmbeddingRequest": { "type": "object", "properties": { "model": { "type": "string" }, "content": { "$ref": "#/components/schemas/GeminiContent" }, "taskType": { "type": "string" }, "title": { "type": "string" }, "outputDimensionality": { "type": "integer" } } }, "GeminiEmbeddingResponse": { "type": "object", "properties": { "embeddings": { "type": "array", "items": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "number" } }, "statistics": { "type": "object", "properties": { "tokenCount": { "type": "integer" } } } } } }, "metadata": { "type": "object", "properties": { "billableCharacterCount": { "type": "integer" } } } } }, "GeminiListModelsResponse": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Model resource name (e.g., models/gemini-pro)" }, "baseModelId": { "type": "string" }, "version": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "inputTokenLimit": { "type": "integer" }, "outputTokenLimit": { "type": "integer" }, "supportedGenerationMethods": { "type": "array", "items": { "type": "string" } }, "thinking": { "type": "boolean", "description": "Whether the model supports thinking mode" }, "temperature": { "type": "number", "description": "Default temperature for the model" }, "maxTemperature": { "type": "number", "description": "Maximum allowed temperature for the model" }, "topP": { "type": "number", "description": "Default nucleus-sampling value" }, "topK": { "type": "integer", "description": "Default top-k sampling value" } } } }, "nextPageToken": { "type": "string" } } }, "GeminiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "status": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "@type": { "type": "string", "description": "Type identifier for the error details" }, "fieldViolations": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" } } } } } } } } } } }, "BedrockConverseRequest": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/BedrockMessage" }, "description": "Array of messages for the conversation" }, "system": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string" } } } } } }, "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] } } } } }, "description": "System messages/prompts" }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "integer" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } } }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object" } } } } }, "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] } } } } } }, "toolChoice": { "type": "object", "properties": { "auto": { "type": "object" }, "any": { "type": "object" }, "tool": { "type": "object", "properties": { "name": { "type": "string" } } } } } } }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, "additionalModelRequestFields": { "type": "object", "description": "Model-specific parameters" }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "standard", "optimized" ] } } }, "promptVariables": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string" } } } }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reserved", "priority", "default", "flex" ] } } }, "fallbacks": { "type": "array", "items": { "type": "string" } } } }, "BedrockConverseResponse": { "type": "object", "properties": { "output": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/BedrockMessage" } } }, "stopReason": { "type": "string", "enum": [ "end_turn", "tool_use", "max_tokens", "stop_sequence", "guardrail_intervened", "content_filtered" ] }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "cacheReadInputTokens": { "type": "integer" }, "cacheWriteInputTokens": { "type": "integer" } } }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "integer" } } }, "additionalModelResponseFields": { "type": "object" }, "trace": { "type": "object" }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "standard", "optimized" ] } } }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reserved", "priority", "default", "flex" ] } } } } }, "BedrockMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/BedrockContentBlock" } } } }, "BedrockContentBlock": { "type": "object", "properties": { "text": { "type": "string" }, "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "jpeg", "png", "gif", "webp" ] }, "source": { "type": "object", "properties": { "bytes": { "type": "string", "format": "byte" } } } } }, "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "type": "object", "properties": { "bytes": { "type": "string", "format": "byte" }, "text": { "type": "string", "description": "Plain text content (for text-based documents)" } } } } }, "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object" } } }, "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/BedrockContentBlock" } }, "status": { "type": "string", "enum": [ "success", "error" ] } } }, "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string" } } } } } }, "reasoningContent": { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } } } } }, "json": { "type": "object", "description": "JSON content for tool call results" }, "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] } } } } }, "BedrockInvokeRequest": { "type": "object", "description": "Raw model invocation request. The body format depends on the model provider.\nFor Anthropic models, use Anthropic format. For other models, use their native format.\n", "properties": { "prompt": { "type": "string", "description": "Text prompt to complete" }, "max_tokens": { "type": "integer" }, "max_tokens_to_sample": { "type": "integer", "description": "Anthropic-style max tokens" }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "stop": { "type": "array", "items": { "type": "string" } }, "stop_sequences": { "type": "array", "items": { "type": "string" }, "description": "Anthropic-style stop sequences" }, "messages": { "type": "array", "items": { "type": "object" }, "description": "For Claude 3 models" }, "system": { "description": "System prompt (string or array of strings)", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "anthropic_version": { "type": "string" } } }, "BedrockInvokeResponse": { "type": "object", "description": "Raw model response. Format depends on the model provider.", "additionalProperties": true }, "BedrockBatchJobRequest": { "type": "object", "required": [ "roleArn", "inputDataConfig", "outputDataConfig" ], "properties": { "modelId": { "type": "string", "description": "Model ID for the batch job (optional, can be specified in request)" }, "jobName": { "type": "string", "description": "Name for the batch job" }, "roleArn": { "type": "string", "description": "IAM role ARN for the job" }, "inputDataConfig": { "type": "object", "properties": { "s3InputDataConfig": { "type": "object", "properties": { "s3Uri": { "type": "string", "description": "S3 URI for input data" } } } } }, "outputDataConfig": { "type": "object", "properties": { "s3OutputDataConfig": { "type": "object", "properties": { "s3Uri": { "type": "string", "description": "S3 URI for output data" } } } } }, "timeoutDurationInHours": { "type": "integer", "description": "Timeout in hours" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "BedrockBatchJobResponse": { "type": "object", "properties": { "jobArn": { "type": "string" }, "status": { "type": "string", "enum": [ "Submitted", "InProgress", "Completed", "Failed", "Stopping", "Stopped", "PartiallyCompleted", "Expired", "Validating", "Scheduled" ] }, "jobName": { "type": "string" }, "modelId": { "type": "string" }, "roleArn": { "type": "string" }, "inputDataConfig": { "type": "object" }, "outputDataConfig": { "type": "object" }, "vpcConfig": { "type": "object", "properties": { "securityGroupIds": { "type": "array", "items": { "type": "string" } }, "subnetIds": { "type": "array", "items": { "type": "string" } } } }, "submitTime": { "type": "string", "format": "date-time" }, "lastModifiedTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "message": { "type": "string" }, "clientRequestToken": { "type": "string" }, "jobExpirationTime": { "type": "string", "format": "date-time" }, "timeoutDurationInHours": { "type": "integer" } } }, "BedrockError": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } } }, "CohereChatRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Model to use for chat completion", "example": "command-r-plus" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/CohereMessage" }, "description": "Array of message objects" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object" } } } } } }, "tool_choice": { "type": "string", "enum": [ "AUTO", "NONE", "REQUIRED" ], "description": "Tool choice mode - AUTO lets the model decide, NONE disables tools, REQUIRED forces tool use" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "p": { "type": "number", "description": "Top-p sampling" }, "k": { "type": "integer", "description": "Top-k sampling" }, "max_tokens": { "type": "integer" }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "stream": { "type": "boolean" }, "safety_mode": { "type": "string", "enum": [ "CONTEXTUAL", "STRICT", "NONE" ] }, "log_probs": { "type": "boolean" }, "strict_tool_choice": { "type": "boolean" }, "thinking": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled" ] }, "token_budget": { "type": "integer", "minimum": 1 } } }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "json_object" ], "description": "Response format type" }, "schema": { "type": "object", "description": "JSON schema for structured output (used with json_object type)" } } } } }, "CohereChatResponse": { "type": "object", "properties": { "id": { "type": "string" }, "finish_reason": { "type": "string", "enum": [ "COMPLETE", "STOP_SEQUENCE", "MAX_TOKENS", "TOOL_CALL", "ERROR", "TIMEOUT" ] }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "image_url": { "type": "object", "properties": { "url": { "type": "string" } } }, "thinking": { "type": "string" }, "document": { "type": "object", "properties": { "data": { "type": "object" }, "id": { "type": "string" } } } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } }, "tool_plan": { "type": "string" } } }, "usage": { "type": "object", "properties": { "billed_units": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of billed input tokens" }, "output_tokens": { "type": "integer", "description": "Number of billed output tokens" }, "search_units": { "type": "integer", "description": "Number of billed search units" }, "classifications": { "type": "integer", "description": "Number of billed classification units" } } }, "tokens": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens produced" } } }, "cached_tokens": { "type": "integer", "description": "Cached tokens" } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "token_ids": { "type": "array", "items": { "type": "integer" }, "description": "Token IDs of each token in text chunk" }, "text": { "type": "string", "description": "Text chunk for log probabilities" }, "logprobs": { "type": "array", "items": { "type": "number" }, "description": "Log probability of each token" } } }, "description": "Log probabilities (if requested)" } } }, "CohereMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "image_url": { "type": "object", "properties": { "url": { "type": "string" } } }, "thinking": { "type": "string" }, "document": { "type": "object", "properties": { "data": { "type": "object" }, "id": { "type": "string" } } } } } } ], "description": "Message content - can be a string or array of content blocks" }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } }, "tool_call_id": { "type": "string" }, "tool_plan": { "type": "string", "description": "Chain-of-thought style reflection (assistant only)" } } }, "CohereEmbeddingRequest": { "type": "object", "required": [ "model", "input_type" ], "properties": { "model": { "type": "string", "description": "ID of an available embedding model", "example": "embed-english-v3.0" }, "input_type": { "type": "string", "description": "Specifies the type of input passed to the model. Required for embedding models v3 and higher." }, "texts": { "type": "array", "items": { "type": "string" }, "description": "Array of strings to embed. Maximum 96 texts per call. At least one of texts, images, or inputs is required.", "maxItems": 96 }, "images": { "type": "array", "items": { "type": "string" }, "description": "Array of image data URIs for multimodal embedding. Maximum 1 image per call. Supports JPEG, PNG, WebP, GIF up to 5MB.", "maxItems": 1 }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "thinking", "document" ] }, "text": { "type": "string" }, "image_url": { "type": "object", "properties": { "url": { "type": "string" } } }, "thinking": { "type": "string" }, "document": { "type": "object", "properties": { "data": { "type": "object" }, "id": { "type": "string" } } } } }, "description": "Array of content blocks (reuses chat content blocks)" } } }, "description": "Array of mixed text/image components for embedding. Maximum 96 per call.", "maxItems": 96 }, "embedding_types": { "type": "array", "items": { "type": "string" }, "description": "Specifies the return format types (float, int8, uint8, binary, ubinary, base64). Defaults to float if unspecified." }, "output_dimension": { "type": "integer", "description": "Number of dimensions for output embeddings (256, 512, 1024, 1536). Available only for embed-v4 and newer models." }, "max_tokens": { "type": "integer", "description": "Maximum tokens to embed per input before truncation." }, "truncate": { "type": "string", "description": "Handling for inputs exceeding token limits. Defaults to END." } } }, "CohereEmbeddingResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Response ID" }, "embeddings": { "type": "object", "description": "Embedding data object with different types", "properties": { "float": { "type": "array", "items": { "type": "array", "items": { "type": "number" } }, "description": "Float embeddings" }, "int8": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } }, "description": "Int8 embeddings" }, "uint8": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } }, "description": "Uint8 embeddings" }, "binary": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } }, "description": "Binary embeddings" }, "ubinary": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } }, "description": "Unsigned binary embeddings" }, "base64": { "type": "array", "items": { "type": "string" }, "description": "Base64-encoded embeddings" } } }, "response_type": { "type": "string", "description": "Response type (embeddings_floats, embeddings_by_type)" }, "texts": { "type": "array", "items": { "type": "string" }, "description": "Original text entries" }, "images": { "type": "array", "items": { "type": "object", "description": "Image information in the response", "properties": { "width": { "type": "integer", "description": "Width in pixels" }, "height": { "type": "integer", "description": "Height in pixels" }, "format": { "type": "string", "description": "Image format" }, "bit_depth": { "type": "integer", "description": "Bit depth" } } }, "description": "Original image entries" }, "meta": { "type": "object", "description": "Metadata in embedding response", "properties": { "api_version": { "type": "object", "description": "API version information", "properties": { "version": { "type": "string", "description": "API version" }, "is_deprecated": { "type": "boolean", "description": "Deprecation status" }, "is_experimental": { "type": "boolean", "description": "Experimental status" } } }, "billed_units": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of billed input tokens" }, "output_tokens": { "type": "integer", "description": "Number of billed output tokens" }, "search_units": { "type": "integer", "description": "Number of billed search units" }, "classifications": { "type": "integer", "description": "Number of billed classification units" } } }, "tokens": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens produced" } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Any warnings" } } } } }, "CohereCountTokensRequest": { "type": "object", "required": [ "text", "model" ], "properties": { "model": { "type": "string", "description": "Model whose tokenizer should be used", "example": "command-r-plus" }, "text": { "type": "string", "description": "Text to tokenize (1-65536 characters)", "minLength": 1, "maxLength": 65536 } } }, "CohereCountTokensResponse": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "integer" }, "description": "Token IDs" }, "token_strings": { "type": "array", "items": { "type": "string" }, "description": "Token strings" }, "meta": { "type": "object", "description": "Metadata returned by the tokenize endpoint", "properties": { "api_version": { "type": "object", "description": "API version metadata", "properties": { "version": { "type": "string", "description": "API version" } } } } } } }, "CohereError": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type" }, "message": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Optional error code" } } }, "SuccessResponse": { "type": "object", "description": "Generic success response", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Operation completed successfully" } } }, "ManagementErrorResponse": { "$ref": "#/components/schemas/BifrostError", "type": "object", "description": "Error response" }, "MessageResponse": { "type": "object", "description": "Simple message response", "properties": { "message": { "type": "string" } } }, "HealthResponse": { "type": "object", "description": "Health check response", "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" }, "components": { "type": "object", "description": "Health status of individual components (config_store, log_store, vector_store)", "additionalProperties": { "type": "string" } } } }, "GetConfigResponse": { "type": "object", "description": "Configuration response", "properties": { "client_config": { "type": "object", "description": "Client configuration", "properties": { "drop_excess_requests": { "type": "boolean", "description": "Whether to drop excess requests when rate limited" }, "prometheus_labels": { "type": "array", "items": { "type": "string" }, "description": "Custom Prometheus labels" }, "allowed_origins": { "type": "array", "items": { "type": "string" }, "description": "Allowed CORS origins" }, "initial_pool_size": { "type": "integer", "description": "Initial connection pool size" }, "enable_logging": { "type": "boolean", "description": "Whether logging is enabled" }, "disable_content_logging": { "type": "boolean", "description": "Whether content logging is disabled" }, "allow_per_request_content_storage_override": { "type": "boolean", "default": false, "description": "Allow individual requests to override content storage via the x-bf-disable-content-logging header or context key. When false (default), per-request overrides are ignored." }, "allow_per_request_raw_override": { "type": "boolean", "default": false, "description": "Allow individual requests to override raw request/response visibility via the x-bf-send-back-raw-request and x-bf-send-back-raw-response headers. When false (default), provider-level settings are authoritative and per-request overrides are ignored." }, "enforce_auth_on_inference": { "type": "boolean", "description": "Whether to enforce virtual key authentication on inference requests" }, "vk_rotation_cooldown": { "type": [ "string", "integer" ], "minimum": 0, "maximum": 2592000000000000, "default": 0, "description": "Cooldown after virtual key rotation - grace period during which the previous key value still authenticates. Writes accept a Go duration string (e.g. \"5m\", \"1h\"); integer values and API responses are nanoseconds (Go duration encoding). 0 disables the grace period. Maximum 30 days." }, "enforce_governance_header": { "type": "boolean", "deprecated": true, "description": "Deprecated: use enforce_auth_on_inference instead" }, "max_request_body_size_mb": { "type": "integer", "description": "Maximum request body size in MB" }, "compat": { "type": "object", "description": "Compat plugin configuration", "properties": { "convert_text_to_chat": { "type": "boolean", "description": "Convert text completion requests to chat" }, "convert_chat_to_responses": { "type": "boolean", "description": "Convert chat completion requests to responses" }, "should_drop_params": { "type": "boolean", "description": "Drop unsupported parameters based on model catalog" }, "should_convert_params": { "type": "boolean", "default": false, "description": "Converts model parameter values that are not supported by the model" } }, "additionalProperties": false }, "log_retention_days": { "type": "integer", "description": "Number of days to retain logs" }, "header_filter_config": { "type": "object", "description": "Header filter configuration", "properties": { "allowlist": { "type": "array", "items": { "type": "string" } }, "denylist": { "type": "array", "items": { "type": "string" } } } }, "mcp_agent_depth": { "type": "integer", "description": "Depth of MCP agent" }, "mcp_tool_execution_timeout": { "type": "integer", "description": "Timeout for MCP tool execution in seconds" }, "mcp_tool_sync_interval": { "type": "integer", "minimum": 0, "description": "Global tool-list sync interval in minutes for MCP clients. Applies to clients whose per-client tool_sync_interval is 0 or omitted; a per-client positive value overrides it. When 0 or unset, a 10-minute default applies.\n" }, "mcp_code_mode_binding_level": { "type": "string", "description": "Binding level for MCP code mode" }, "required_headers": { "type": "array", "items": { "type": "string" }, "description": "Headers that must be present on every request. Requests missing any of these headers are rejected with 400. Case-insensitive matching." }, "logging_headers": { "type": "array", "items": { "type": "string" }, "description": "Headers to capture in log metadata. Values are extracted from incoming requests and stored in the metadata field of log entries. Case-insensitive matching. No restart required." }, "mcp_external_client_url": { "oneOf": [ { "type": "string", "description": "Plain URL or env var reference (e.g. \"env.MY_VAR\")" }, { "type": "object", "properties": { "value": { "type": "string" }, "env_var": { "type": "string" }, "from_env": { "type": "boolean" } }, "additionalProperties": false } ], "description": "Public base URL Bifrost uses as the redirect_uri when acting as an OAuth client to upstream MCP servers (Notion, Jira, etc.). Set when Bifrost's callback endpoint is reached via a different URL than its server-side metadata. Supports env var syntax (\"env.MY_VAR\").\n" }, "mcp_server_auth_mode": { "type": "string", "enum": [ "headers", "both", "oauth" ], "default": "headers", "description": "How /mcp authenticates inbound MCP clients. 'headers' (default): VK/api-key/session headers only, discovery disabled. 'both': accepts header credentials and Bifrost-issued JWTs, discovery enabled. 'oauth': Bifrost JWTs only — disables VK/header MCP access.\n" }, "oauth2_server_config": { "type": "object", "description": "OAuth2 authorization server settings for /mcp. Only relevant when mcp_server_auth_mode is 'both' or 'oauth'.\n", "properties": { "issuer_url": { "oneOf": [ { "type": "string", "description": "Plain URL or env var reference (e.g. \"env.MY_VAR\")" }, { "type": "object", "properties": { "value": { "type": "string" }, "env_var": { "type": "string" }, "from_env": { "type": "boolean" } }, "additionalProperties": false } ], "description": "Stable public URL advertised as the OAuth2 AS issuer in discovery documents and the JWT iss claim. Required for multi-host deployments; single-host can omit it (falls back to the request Host header). Supports env var syntax (\"env.MY_VAR\").\n" }, "auth_code_ttl": { "type": "integer", "minimum": 1, "maximum": 900, "default": 300, "description": "Lifetime of the single-use authorization code in seconds (default 300, max 900 = 15 minutes)." }, "access_token_ttl": { "type": "integer", "minimum": 1, "default": 600, "description": "Lifetime of the issued JWT Bearer token in seconds (default 600)." }, "disable_vk_identity": { "type": "boolean", "default": false, "description": "Require identity-provider login: virtual-key identity is removed from the consent flow, and existing virtual-key-mode grants are rejected at /mcp and denied on refresh. Only meaningful when mcp_server_auth_mode is 'oauth' and an identity provider is configured. Anonymous session identity is governed separately by enforce_auth_on_inference.\n" } }, "additionalProperties": false } } }, "framework_config": { "type": "object", "description": "Framework configuration", "properties": { "id": { "type": "integer", "description": "Unique identifier for the framework config" }, "pricing_url": { "type": "string", "description": "URL for pricing data" }, "pricing_sync_interval": { "type": "integer", "format": "int64", "description": "Pricing sync interval in seconds" } } }, "auth_config": { "type": "object", "description": "Absent when no admin account has been configured yet (first-time setup). Once an admin account exists, this is always present. Available starting in Bifrost 2.0.0-prerelease3; earlier versions always returned this field.", "properties": { "admin_username": { "type": "string" }, "admin_password": { "type": "string", "description": "Password (redacted as in responses)" }, "is_enabled": { "type": "boolean" }, "disable_auth_on_inference": { "type": "boolean", "deprecated": true, "description": "Deprecated and ignored. Use client_config.enforce_auth_on_inference instead." } } }, "is_db_connected": { "type": "boolean" }, "is_cache_connected": { "type": "boolean" }, "is_logs_connected": { "type": "boolean" }, "proxy_config": { "type": "object", "description": "Global proxy configuration", "properties": { "enabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "http", "socks5", "tcp" ] }, "url": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string", "description": "Password (redacted as in responses)" }, "no_proxy": { "type": "string" }, "timeout": { "type": "integer" }, "skip_tls_verify": { "type": "boolean" }, "enable_for_scim": { "type": "boolean" }, "enable_for_inference": { "type": "boolean" }, "enable_for_api": { "type": "boolean" } } }, "restart_required": { "type": "object", "description": "Restart required configuration", "properties": { "required": { "type": "boolean" }, "reason": { "type": "string" } } } } }, "UpdateConfigRequest": { "type": "object", "description": "Update configuration request", "properties": { "client_config": { "type": "object", "description": "Client configuration", "properties": { "drop_excess_requests": { "type": "boolean", "description": "Whether to drop excess requests when rate limited" }, "prometheus_labels": { "type": "array", "items": { "type": "string" }, "description": "Custom Prometheus labels" }, "allowed_origins": { "type": "array", "items": { "type": "string" }, "description": "Allowed CORS origins" }, "initial_pool_size": { "type": "integer", "description": "Initial connection pool size" }, "enable_logging": { "type": "boolean", "description": "Whether logging is enabled" }, "disable_content_logging": { "type": "boolean", "description": "Whether content logging is disabled" }, "allow_per_request_content_storage_override": { "type": "boolean", "default": false, "description": "Allow individual requests to override content storage via the x-bf-disable-content-logging header or context key. When false (default), per-request overrides are ignored." }, "allow_per_request_raw_override": { "type": "boolean", "default": false, "description": "Allow individual requests to override raw request/response visibility via the x-bf-send-back-raw-request and x-bf-send-back-raw-response headers. When false (default), provider-level settings are authoritative and per-request overrides are ignored." }, "enforce_auth_on_inference": { "type": "boolean", "description": "Whether to enforce virtual key authentication on inference requests" }, "vk_rotation_cooldown": { "type": [ "string", "integer" ], "minimum": 0, "maximum": 2592000000000000, "default": 0, "description": "Cooldown after virtual key rotation - grace period during which the previous key value still authenticates. Writes accept a Go duration string (e.g. \"5m\", \"1h\"); integer values and API responses are nanoseconds (Go duration encoding). 0 disables the grace period. Maximum 30 days." }, "enforce_governance_header": { "type": "boolean", "deprecated": true, "description": "Deprecated: use enforce_auth_on_inference instead" }, "max_request_body_size_mb": { "type": "integer", "description": "Maximum request body size in MB" }, "compat": { "type": "object", "description": "Compat plugin configuration", "properties": { "convert_text_to_chat": { "type": "boolean", "description": "Convert text completion requests to chat" }, "convert_chat_to_responses": { "type": "boolean", "description": "Convert chat completion requests to responses" }, "should_drop_params": { "type": "boolean", "description": "Drop unsupported parameters based on model catalog" }, "should_convert_params": { "type": "boolean", "default": false, "description": "Converts model parameter values that are not supported by the model" } }, "additionalProperties": false }, "log_retention_days": { "type": "integer", "description": "Number of days to retain logs" }, "header_filter_config": { "type": "object", "description": "Header filter configuration", "properties": { "allowlist": { "type": "array", "items": { "type": "string" } }, "denylist": { "type": "array", "items": { "type": "string" } } } }, "mcp_agent_depth": { "type": "integer", "description": "Depth of MCP agent" }, "mcp_tool_execution_timeout": { "type": "integer", "description": "Timeout for MCP tool execution in seconds" }, "mcp_tool_sync_interval": { "type": "integer", "minimum": 0, "description": "Global tool-list sync interval in minutes for MCP clients. Applies to clients whose per-client tool_sync_interval is 0 or omitted; a per-client positive value overrides it. When 0 or unset, a 10-minute default applies.\n" }, "mcp_code_mode_binding_level": { "type": "string", "description": "Binding level for MCP code mode" }, "required_headers": { "type": "array", "items": { "type": "string" }, "description": "Headers that must be present on every request. Requests missing any of these headers are rejected with 400. Case-insensitive matching." }, "logging_headers": { "type": "array", "items": { "type": "string" }, "description": "Headers to capture in log metadata. Values are extracted from incoming requests and stored in the metadata field of log entries. Case-insensitive matching. No restart required." }, "mcp_external_client_url": { "oneOf": [ { "type": "string", "description": "Plain URL or env var reference (e.g. \"env.MY_VAR\")" }, { "type": "object", "properties": { "value": { "type": "string" }, "env_var": { "type": "string" }, "from_env": { "type": "boolean" } }, "additionalProperties": false } ], "description": "Public base URL Bifrost uses as the redirect_uri when acting as an OAuth client to upstream MCP servers (Notion, Jira, etc.). Set when Bifrost's callback endpoint is reached via a different URL than its server-side metadata. Supports env var syntax (\"env.MY_VAR\").\n" }, "mcp_server_auth_mode": { "type": "string", "enum": [ "headers", "both", "oauth" ], "default": "headers", "description": "How /mcp authenticates inbound MCP clients. 'headers' (default): VK/api-key/session headers only, discovery disabled. 'both': accepts header credentials and Bifrost-issued JWTs, discovery enabled. 'oauth': Bifrost JWTs only — disables VK/header MCP access.\n" }, "oauth2_server_config": { "type": "object", "description": "OAuth2 authorization server settings for /mcp. Only relevant when mcp_server_auth_mode is 'both' or 'oauth'.\n", "properties": { "issuer_url": { "oneOf": [ { "type": "string", "description": "Plain URL or env var reference (e.g. \"env.MY_VAR\")" }, { "type": "object", "properties": { "value": { "type": "string" }, "env_var": { "type": "string" }, "from_env": { "type": "boolean" } }, "additionalProperties": false } ], "description": "Stable public URL advertised as the OAuth2 AS issuer in discovery documents and the JWT iss claim. Required for multi-host deployments; single-host can omit it (falls back to the request Host header). Supports env var syntax (\"env.MY_VAR\").\n" }, "auth_code_ttl": { "type": "integer", "minimum": 1, "maximum": 900, "default": 300, "description": "Lifetime of the single-use authorization code in seconds (default 300, max 900 = 15 minutes)." }, "access_token_ttl": { "type": "integer", "minimum": 1, "default": 600, "description": "Lifetime of the issued JWT Bearer token in seconds (default 600)." }, "disable_vk_identity": { "type": "boolean", "default": false, "description": "Require identity-provider login: virtual-key identity is removed from the consent flow, and existing virtual-key-mode grants are rejected at /mcp and denied on refresh. Only meaningful when mcp_server_auth_mode is 'oauth' and an identity provider is configured. Anonymous session identity is governed separately by enforce_auth_on_inference.\n" } }, "additionalProperties": false } } }, "framework_config": { "type": "object", "description": "Framework configuration", "properties": { "id": { "type": "integer", "description": "Unique identifier for the framework config" }, "pricing_url": { "type": "string", "description": "URL for pricing data" }, "pricing_sync_interval": { "type": "integer", "format": "int64", "description": "Pricing sync interval in seconds" } } }, "auth_config": { "allOf": [ { "type": "object", "description": "Authentication configuration", "properties": { "admin_username": { "type": "string" }, "admin_password": { "type": "string", "description": "Password (redacted as in responses)" }, "is_enabled": { "type": "boolean" }, "disable_auth_on_inference": { "type": "boolean", "deprecated": true, "description": "Deprecated and ignored. Use client_config.enforce_auth_on_inference instead." } } }, { "type": "object", "properties": { "setup_token": { "type": "string", "description": "Available starting in Bifrost 2.0.0-prerelease3. Bootstrap token, required only when this request creates the very first admin account (i.e. no admin account exists yet). Must match the setup token configured by the operator via setup_token in config.json (or the BIFROST_SETUP_TOKEN environment variable); never persisted or returned by GET /api/config. If the operator hasn't configured a setup token, requests that would create the first admin account are rejected until they do. Once an admin account exists, this field is ignored." } } } ] } }, "example": { "auth_config": { "admin_username": "admin", "admin_password": "env.BIFROST_ADMIN_PASSWORD", "is_enabled": true, "setup_token": "" } } }, "Version": { "type": "string", "description": "Version information", "example": "1.0.0" }, "LoginRequest": { "type": "object", "description": "Login request", "required": [ "username", "password" ], "properties": { "username": { "type": "string" }, "password": { "type": "string" } } }, "LoginResponse": { "type": "object", "description": "Login response", "properties": { "message": { "type": "string", "example": "Login successful" }, "token": { "type": "string", "description": "Session token" } } }, "IsAuthEnabledResponse": { "type": "object", "description": "Auth enabled status response", "properties": { "is_auth_enabled": { "type": "boolean" }, "has_valid_token": { "type": "boolean" } } }, "ProviderResponse": { "type": "object", "description": "Provider configuration response", "properties": { "name": { "$ref": "#/components/schemas/ModelProvider" }, "network_config": { "$ref": "#/components/schemas/NetworkConfig" }, "concurrency_and_buffer_size": { "$ref": "#/components/schemas/ConcurrencyAndBufferSize" }, "proxy_config": { "type": "object", "description": "Proxy configuration", "properties": { "type": { "type": "string", "enum": [ "none", "http", "socks5", "environment" ] }, "url": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "ca_cert_pem": { "type": "string" } } }, "send_back_raw_request": { "type": "boolean" }, "send_back_raw_response": { "type": "boolean" }, "store_raw_request_response": { "type": "boolean" }, "custom_provider_config": { "type": "object", "description": "Custom provider configuration", "properties": { "is_key_less": { "type": "boolean" }, "base_provider_type": { "$ref": "#/components/schemas/ModelProvider" }, "allowed_requests": { "type": "object", "description": "Allowed request types for custom providers", "properties": { "list_models": { "type": "boolean" }, "text_completion": { "type": "boolean" }, "text_completion_stream": { "type": "boolean" }, "chat_completion": { "type": "boolean" }, "chat_completion_stream": { "type": "boolean" }, "responses": { "type": "boolean" }, "responses_stream": { "type": "boolean" }, "count_tokens": { "type": "boolean" }, "embedding": { "type": "boolean" }, "speech": { "type": "boolean" }, "speech_stream": { "type": "boolean" }, "transcription": { "type": "boolean" }, "transcription_stream": { "type": "boolean" }, "image_generation": { "type": "boolean" }, "image_generation_stream": { "type": "boolean" }, "batch_create": { "type": "boolean" }, "batch_list": { "type": "boolean" }, "batch_retrieve": { "type": "boolean" }, "batch_cancel": { "type": "boolean" }, "batch_results": { "type": "boolean" }, "file_upload": { "type": "boolean" }, "file_list": { "type": "boolean" }, "file_retrieve": { "type": "boolean" }, "file_delete": { "type": "boolean" }, "file_content": { "type": "boolean" } } }, "request_path_overrides": { "type": "object", "additionalProperties": { "type": "string" } } } }, "provider_status": { "type": "string", "enum": [ "active", "error", "deleted" ], "description": "Status of the provider" }, "status": { "type": "string", "description": "Operational status (e.g., list_models_failed)" }, "description": { "type": "string", "description": "Error/status description" }, "config_hash": { "type": "string", "description": "Hash of config.json version, used for change detection" } } }, "ListProvidersResponse": { "type": "object", "description": "List providers response", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderResponse" } }, "total": { "type": "integer" } } }, "AddProviderRequest": { "type": "object", "description": "Add provider request. Keys are managed separately via /api/providers/{provider}/keys.", "required": [ "provider" ], "properties": { "provider": { "$ref": "#/components/schemas/ModelProvider" }, "network_config": { "$ref": "#/components/schemas/NetworkConfig" }, "concurrency_and_buffer_size": { "$ref": "#/components/schemas/ConcurrencyAndBufferSize" }, "proxy_config": { "type": "object", "description": "Proxy configuration", "properties": { "type": { "type": "string", "enum": [ "none", "http", "socks5", "environment" ] }, "url": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "ca_cert_pem": { "type": "string" } } }, "send_back_raw_request": { "type": "boolean" }, "send_back_raw_response": { "type": "boolean" }, "store_raw_request_response": { "type": "boolean" }, "custom_provider_config": { "type": "object", "description": "Custom provider configuration", "properties": { "is_key_less": { "type": "boolean" }, "base_provider_type": { "$ref": "#/components/schemas/ModelProvider" }, "allowed_requests": { "type": "object", "description": "Allowed request types for custom providers", "properties": { "list_models": { "type": "boolean" }, "text_completion": { "type": "boolean" }, "text_completion_stream": { "type": "boolean" }, "chat_completion": { "type": "boolean" }, "chat_completion_stream": { "type": "boolean" }, "responses": { "type": "boolean" }, "responses_stream": { "type": "boolean" }, "count_tokens": { "type": "boolean" }, "embedding": { "type": "boolean" }, "speech": { "type": "boolean" }, "speech_stream": { "type": "boolean" }, "transcription": { "type": "boolean" }, "transcription_stream": { "type": "boolean" }, "image_generation": { "type": "boolean" }, "image_generation_stream": { "type": "boolean" }, "batch_create": { "type": "boolean" }, "batch_list": { "type": "boolean" }, "batch_retrieve": { "type": "boolean" }, "batch_cancel": { "type": "boolean" }, "batch_results": { "type": "boolean" }, "file_upload": { "type": "boolean" }, "file_list": { "type": "boolean" }, "file_retrieve": { "type": "boolean" }, "file_delete": { "type": "boolean" }, "file_content": { "type": "boolean" } } }, "request_path_overrides": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "UpdateProviderRequest": { "type": "object", "description": "Update provider request. Keys are managed separately via /api/providers/{provider}/keys.", "properties": { "network_config": { "$ref": "#/components/schemas/NetworkConfig" }, "concurrency_and_buffer_size": { "$ref": "#/components/schemas/ConcurrencyAndBufferSize" }, "proxy_config": { "type": "object", "description": "Proxy configuration", "properties": { "type": { "type": "string", "enum": [ "none", "http", "socks5", "environment" ] }, "url": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "ca_cert_pem": { "type": "string" } } }, "send_back_raw_request": { "type": "boolean" }, "send_back_raw_response": { "type": "boolean" }, "store_raw_request_response": { "type": "boolean" }, "custom_provider_config": { "type": "object", "description": "Custom provider configuration", "properties": { "is_key_less": { "type": "boolean" }, "base_provider_type": { "$ref": "#/components/schemas/ModelProvider" }, "allowed_requests": { "type": "object", "description": "Allowed request types for custom providers", "properties": { "list_models": { "type": "boolean" }, "text_completion": { "type": "boolean" }, "text_completion_stream": { "type": "boolean" }, "chat_completion": { "type": "boolean" }, "chat_completion_stream": { "type": "boolean" }, "responses": { "type": "boolean" }, "responses_stream": { "type": "boolean" }, "count_tokens": { "type": "boolean" }, "embedding": { "type": "boolean" }, "speech": { "type": "boolean" }, "speech_stream": { "type": "boolean" }, "transcription": { "type": "boolean" }, "transcription_stream": { "type": "boolean" }, "image_generation": { "type": "boolean" }, "image_generation_stream": { "type": "boolean" }, "batch_create": { "type": "boolean" }, "batch_list": { "type": "boolean" }, "batch_retrieve": { "type": "boolean" }, "batch_cancel": { "type": "boolean" }, "batch_results": { "type": "boolean" }, "file_upload": { "type": "boolean" }, "file_list": { "type": "boolean" }, "file_retrieve": { "type": "boolean" }, "file_delete": { "type": "boolean" }, "file_content": { "type": "boolean" } } }, "request_path_overrides": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "Key": { "type": "object", "description": "API key configuration", "properties": { "id": { "type": "string", "description": "Unique identifier for the key" }, "name": { "type": "string", "description": "Name of the key" }, "value": { "type": "object", "description": "API key value (redacted in responses)", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "models": { "type": "array", "items": { "type": "string" }, "description": "List of models this key can access (whitelist)" }, "blacklisted_models": { "type": "array", "items": { "type": "string" }, "description": "List of models this key cannot access (blacklist)" }, "weight": { "type": "number", "description": "Weight for load balancing" }, "aliases": { "type": "object", "propertyNames": { "minLength": 1 }, "additionalProperties": { "type": "string", "minLength": 1 }, "description": "Model alias mappings - maps a user-facing model name to a provider-specific identifier (deployment name, inference profile ID, fine-tuned model ID, etc.)" }, "azure_key_config": { "type": "object", "description": "Azure-specific key configuration", "properties": { "endpoint": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "api_version": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "client_id": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "client_secret": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "tenant_id": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "List of scopes to use for authentication" } } }, "vertex_key_config": { "type": "object", "description": "Vertex-specific key configuration", "properties": { "project_id": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "project_number": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "region": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "auth_credentials": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } } } }, "bedrock_key_config": { "type": "object", "description": "AWS Bedrock-specific key configuration", "properties": { "access_key": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "secret_key": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "session_token": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "region": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "arn": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "batch_s3_config": { "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "bucket_name": { "type": "string" }, "prefix": { "type": "string" }, "is_default": { "type": "boolean" } } } } } } } }, "vllm_key_config": { "type": "object", "description": "VLLM-specific key configuration", "properties": { "url": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "model_name": { "type": "string" } }, "required": [ "url" ] }, "ollama_key_config": { "type": "object", "description": "Ollama-specific key configuration", "properties": { "url": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } } }, "required": [ "url" ] }, "sgl_key_config": { "type": "object", "description": "SGLang-specific key configuration", "properties": { "url": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } } }, "required": [ "url" ] }, "replicate_key_config": { "type": "object", "description": "Replicate-specific key configuration", "properties": { "use_deployments_endpoint": { "type": "boolean", "description": "Whether to use the deployments endpoint instead of the models endpoint" } } }, "enabled": { "type": "boolean", "description": "Whether the key is active (defaults to true)" }, "use_for_batch_api": { "type": "boolean", "description": "Whether this key can be used for batch API operations" }, "config_hash": { "type": "string", "description": "Hash of config.json version, used for change detection" }, "status": { "type": "string", "description": "Status of key (e.g., success, list_models_failed)" }, "description": { "type": "string", "description": "Error or status description for the key" } } }, "ListProviderKeysResponse": { "type": "object", "description": "Response for listing keys for a provider", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } }, "total": { "type": "integer" } } }, "NetworkConfig": { "type": "object", "description": "Network configuration for provider connections", "properties": { "base_url": { "type": "string", "description": "Base URL for the provider (optional)" }, "extra_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional headers to include in requests" }, "default_request_timeout_in_seconds": { "type": "integer", "description": "Default timeout for requests" }, "max_retries": { "type": "integer", "description": "Maximum number of retries" }, "retry_backoff_initial": { "type": "integer", "format": "int64", "description": "Initial backoff duration in milliseconds" }, "retry_backoff_max": { "type": "integer", "format": "int64", "description": "Maximum backoff duration in milliseconds" }, "insecure_skip_verify": { "type": "boolean", "description": "Disable TLS certificate verification for provider connections. This bypasses server certificate validation and should be used only as a last resort when a trusted CA chain cannot be configured. Prefer ca_cert_pem for self-signed or private CA deployments." }, "ca_cert_pem": { "type": "string", "description": "PEM-encoded CA certificate to trust for provider endpoint connections (e.g. self-signed or internal CA)" }, "allow_private_network": { "type": "boolean", "default": false, "description": "Allow connections to RFC 1918 private IPs (10.x, 172.16.x, 192.168.x). Enable for providers on a k8s pod network, LAN, or private VPC. Loopback addresses (localhost, 127.0.0.1, ::1) remain allowed regardless of this setting. Link-local addresses (169.254.x.x) are always blocked." } } }, "ConcurrencyAndBufferSize": { "type": "object", "description": "Concurrency settings", "properties": { "concurrency": { "type": "integer", "description": "Number of concurrent operations" }, "buffer_size": { "type": "integer", "description": "Size of the buffer" } } }, "Plugin": { "type": "object", "description": "Plugin configuration", "properties": { "id": { "type": "integer", "description": "Plugin ID (auto-generated)" }, "name": { "type": "string", "description": "Display name of the plugin (from config)" }, "actualName": { "type": "string", "description": "Actual plugin name from GetName() (used as map key in plugin status). Only populated for active plugins." }, "enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true }, "isCustom": { "type": "boolean" }, "path": { "type": "string" }, "status": { "type": "object", "description": "Current plugin status including types array (only populated for active plugins)", "properties": { "name": { "type": "string", "description": "Display name of the plugin" }, "status": { "type": "string", "enum": [ "active", "error", "disabled", "loading", "uninitialized", "unloaded", "loaded" ] }, "logs": { "type": "array", "items": { "type": "string" } }, "types": { "type": "array", "description": "Plugin types indicating which interfaces the plugin implements", "items": { "type": "string", "enum": [ "llm", "mcp", "http", "observability" ] } } }, "example": { "name": "my_custom_plugin", "status": "active", "logs": [ "plugin my_custom_plugin initialized successfully" ], "types": [ "llm", "http" ] } }, "created_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int16" }, "updated_at": { "type": "string", "format": "date-time" }, "config_hash": { "type": "string" } }, "example": { "name": "my_custom_plugin", "actualName": "MyCustomPlugin", "enabled": true, "config": { "api_key": "xxx" }, "isCustom": true, "path": "/plugins/my_custom_plugin.so", "status": { "name": "my_custom_plugin", "status": "active", "logs": [ "plugin my_custom_plugin initialized successfully" ], "types": [ "llm", "http" ] } } }, "ListPluginsResponse": { "type": "object", "description": "List plugins response", "properties": { "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/Plugin" } }, "count": { "type": "integer" } } }, "CreatePluginRequest": { "type": "object", "description": "Create plugin request", "required": [ "name" ], "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true }, "path": { "type": "string" } } }, "UpdatePluginRequest": { "type": "object", "description": "Update plugin request", "properties": { "enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true }, "path": { "type": "string" } } }, "MCPClient": { "type": "object", "description": "Connected MCP client with its tools", "properties": { "config": { "$ref": "#/components/schemas/MCPClientConfig" }, "tools": { "type": "array", "items": { "type": "object", "description": "Tool function definition", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true }, "strict": { "type": "boolean" } } } }, "state": { "type": "string", "enum": [ "healthy", "unstable", "error", "pending_verification", "needs_reauth", "disabled", "degraded" ], "description": "Connection state of an MCP client:\n- healthy: Bifrost's own periodic connection check (ping/list_tools for\n sticky clients, list_tools for per-call clients) most recently\n succeeded.\n- unstable: The periodic connection check most recently failed with a\n transient-classified error. Purely informational — unlike\n needs_reauth, this never gates execution; tool calls are still\n attempted normally. Self-heals to healthy on the next successful\n check, no human action required.\n- error: A data-consistency fallback used only when a client is\n registered in the config store but missing from the runtime manager\n entirely — a deeper anomaly than anything in the normal\n connect/health-check lifecycle, which never assigns this value itself.\n- pending_verification: Declared (typically via config.json) but the one-time\n admin verification has not been completed yet. Complete it via\n POST /api/mcp/client/{id}/initiate-verification (auth_type oauth /\n per_user_oauth) or POST /api/mcp/client/{id}/verify-headers\n (auth_type per_user_headers).\n- needs_reauth: Setup completed at least once, but a credential an admin is\n responsible for has permanently died and needs a human to repair it.\n For shared OAuth clients the connection credential itself was\n rejected/expired with no silent recovery; the state is sticky (the health\n monitor will not clobber it) until an admin runs\n POST /api/mcp/client/{id}/reauthorize. For per-user clients this is a\n response-only projection — computed at list-time, never stored in the\n runtime manager — meaning the retained admin discovery credential\n needs repair; end-user credentials and tool calls keep working, only\n periodic tool-list refresh pauses. Overlays onto both healthy and\n unstable runtime readings, never onto disabled or\n pending_verification. Repair via reauthorize (per_user_oauth),\n verify-headers with fresh sample values (per_user_headers), or\n verify-exchange (token_exchange, which re-exchanges the signed-in\n admin's own identity token — no sample values to supply).\n- disabled: Client has been intentionally disabled; no connection or workers are active\n- degraded: A read-time cluster aggregate, never a single node's own\n local state — multiple instances of a distributed deployment each\n currently hold a different self-reported state for the same client.\n Only meaningful for states that can genuinely vary per instance\n (healthy, unstable, pending_verification); needs_reauth/disabled are\n config-sourced facts expected to already agree everywhere. Never\n appears in a single-instance deployment.\n" }, "vk_configs": { "type": "array", "items": { "type": "object", "description": "Per-virtual-key tool access configuration as returned in list/get responses", "properties": { "virtual_key_id": { "type": "string", "description": "ID of the virtual key" }, "virtual_key_name": { "type": "string", "description": "Display name of the virtual key" }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "Tools this virtual key is allowed to call on this MCP client.\n[\"*\"] => all tools allowed\n[\"tool1\", \"tool2\"] => only the specified tools\n" } } }, "description": "Virtual key assignments for this MCP client" } } }, "MCPClientConfig": { "type": "object", "description": "Full MCP client configuration (used in responses)", "properties": { "client_id": { "type": "string", "description": "Unique identifier for the MCP client" }, "name": { "type": "string", "description": "Display name for the MCP client" }, "is_code_mode_client": { "type": "boolean", "description": "Whether this client is available in code mode" }, "connection_type": { "type": "string", "enum": [ "http", "stdio", "sse", "inprocess" ], "description": "Connection type for MCP client" }, "connection_string": { "type": "string", "description": "HTTP or SSE URL (required for HTTP or SSE connections)" }, "stdio_config": { "type": "object", "description": "STDIO configuration for MCP client", "properties": { "command": { "type": "string", "description": "Executable command to run" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Command line arguments" }, "envs": { "type": "array", "items": { "type": "string" }, "description": "Environment variables required" } } }, "tls_config": { "type": "object", "description": "TLS configuration for HTTP and SSE connections.", "properties": { "insecure_skip_verify": { "type": "boolean", "description": "Disable TLS certificate verification. Development/testing only." }, "ca_cert_pem": { "type": "string", "description": "PEM-encoded CA certificate. Supports env.VAR_NAME syntax for input.\nResponses return a redacted placeholder rather than the raw PEM value.\n" } } }, "auth_type": { "type": "string", "enum": [ "none", "headers", "oauth", "per_user_oauth", "per_user_headers", "token_exchange" ], "description": "Authentication type for the MCP connection" }, "oauth_config_id": { "type": "string", "description": "OAuth config ID for OAuth authentication.\nReferences the oauth_configs table.\nOnly set when auth_type is \"oauth\".\n" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests.\nOnly used when auth_type is \"headers\".\n" }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "Include-only list for tools.\n[\"*\"] => all tools are included\n[] => no tools are included\n[\"tool1\", \"tool2\"] => include only the specified tools\n" }, "tools_to_auto_execute": { "type": "array", "items": { "type": "string" }, "description": "List of tools that can be auto-executed without user approval.\nMust be a subset of tools_to_execute.\n[\"*\"] => all executable tools can be auto-executed\n[] => no tools are auto-executed\n[\"tool1\", \"tool2\"] => only specified tools can be auto-executed\n" }, "tool_pricing": { "type": "object", "additionalProperties": { "type": "number", "format": "double" }, "description": "Per-tool cost in USD for execution.\nKey is the tool name, value is the cost per execution.\nExample: {\"read_file\": 0.001, \"write_file\": 0.002}\n" }, "allow_on_all_virtual_keys": { "type": "boolean", "default": false, "description": "When true, this MCP client's tools are accessible to all virtual keys without requiring\nexplicit per-key assignment. All tools are allowed by default. If a virtual key has an\nexplicit MCP config for this client, that config takes precedence and overrides this behaviour.\n" }, "per_user_header_keys": { "type": "array", "items": { "type": "string" }, "description": "For `per_user_headers` clients only. The list of header names each end-user\nmust supply via the inline-401 flow. Header values themselves are stored\nper-user in a separate table (surfaced on `/api/mcp/sessions`).\n" }, "token_exchange": { "type": "object", "required": [ "audience" ], "properties": { "audience": { "type": "string", "minLength": 1, "description": "Resource identifier this server is scoped to at the identity provider (e.g. \"api://jira-mcp\")" }, "use_idp_credentials": { "type": "boolean", "description": "When true, performs the exchange as the SSO login application itself\ninstead of client_id/client_secret below, which are then ignored.\nSome providers require this: Microsoft Entra ID's on-behalf-of grant\nonly accepts an assertion audienced to the exchanging application,\nand the SSO login flow always requests a token self-audienced to the\nSSO application, so a separate exchange application can never\nreceive a usable one.\n" }, "client_id": { "type": "string", "minLength": 1, "description": "The identity-provider application authorized to perform exchanges for\nthis audience — typically a dedicated registration carrying the\ntoken-exchange (or on-behalf-of) grant, separate from the SSO login\napplication. Required unless use_idp_credentials is true. Supports\nenv.VAR_NAME and vault.path references. Redacted in API responses.\n" }, "client_secret": { "type": "string", "description": "Secret for the exchange application; omit for public clients. Ignored\nwhen use_idp_credentials is true. Supports env.VAR_NAME and\nvault.path references. Redacted in API responses.\n" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes to request on the exchanged token. Include\n\"offline_access\" (where the identity provider supports it) so the\nretained admin discovery credential gets a refresh token and stays\nself-renewing.\n" }, "authorization_server_url": { "type": "string", "description": "Overrides the Authorization Server the exchange request is sent to.\nOnly needed when the audience is registered on a different\nAuthorization Server than the one used for SSO login (e.g. Okta's\nper-resource Custom Authorization Servers). Leave unset to use the\ndeployment's SSO login issuer, which is correct for providers with a\nsingle tenant-wide token endpoint (Entra, Auth0).\n" } }, "allOf": [ { "if": { "not": { "properties": { "use_idp_credentials": { "const": true } }, "required": [ "use_idp_credentials" ] } }, "then": { "required": [ "client_id" ], "description": "client_id is required unless use_idp_credentials is true, in which\ncase the exchange uses the SSO login application's own credentials\ninstead.\n" } } ], "additionalProperties": false, "description": "For `token_exchange` clients only. `client_id` and `client_secret` are\nredacted in this response.\n" }, "disabled": { "type": "boolean", "default": false, "description": "Whether the client is intentionally disabled.\nWhen true, the client has no active connection or workers and its tools are not available for inference.\n" } } }, "ExecuteToolRequest": { "oneOf": [ { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } }, "title": "Chat (Default)", "description": "Chat format - uses ChatAssistantMessageToolCall schema" }, { "type": "object", "description": "Responses format - uses ResponsesToolMessage schema", "required": [ "name" ], "properties": { "call_id": { "type": "string", "description": "Common call ID for tool calls and outputs" }, "name": { "type": "string", "description": "Tool function name (required for execution)" }, "arguments": { "type": "string", "description": "Tool function arguments as JSON string" }, "output": { "type": "object", "description": "Tool execution output", "additionalProperties": true }, "action": { "type": "object", "description": "Tool action configuration", "additionalProperties": true }, "error": { "type": "string", "description": "Error message if tool execution failed" } }, "title": "Responses" } ], "description": "MCP tool execution request. The schema depends on the `format` query parameter:\n- `format=chat` or empty (default): Use `ChatAssistantMessageToolCall` schema\n- `format=responses`: Use `ResponsesToolMessage` schema\n" }, "MCPAuthType": { "type": "string", "enum": [ "none", "headers", "oauth", "per_user_oauth", "per_user_headers", "token_exchange" ], "description": "Authentication type for MCP connections:\n- none: No authentication\n- headers: Static header-based authentication (admin sets API keys / custom headers once, shared by all callers)\n- oauth: OAuth 2.0 authentication (server-level, admin authenticates once)\n- per_user_oauth: Per-user OAuth 2.0 authentication (each user authenticates individually)\n- per_user_headers: Per-user headers (each user submits their own header values; admin declares the schema)\n- token_exchange: Delegated token exchange (each caller's own identity-provider token is\n exchanged for a short-lived token scoped to this server on every call; nothing is\n stored per caller). Requires an enabled identity-provider integration (enterprise).\n" }, "OAuthConfigRequest": { "type": "object", "description": "OAuth configuration for an MCP client. Used both when creating a client\n(initiates the OAuth flow) and when updating one (rotates the stored\nOAuth config in place; see MCPClientUpdateRequest.oauth_config).\n", "properties": { "client_id": { "allOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } } ], "description": "OAuth client ID. Optional if client supports dynamic client registration (RFC 7591).\nIf not provided, the server_url must be set for OAuth discovery and dynamic registration.\nSupports env./vault. references.\n" }, "client_secret": { "allOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } } ], "description": "OAuth client secret. Optional for public clients using PKCE or clients obtained via dynamic registration.\nSupports env./vault. references.\n" }, "authorize_url": { "type": "string", "description": "OAuth authorization endpoint URL. Optional - will be discovered from server_url if not provided.\n" }, "token_url": { "type": "string", "description": "OAuth token endpoint URL. Optional - will be discovered from server_url if not provided.\n" }, "registration_url": { "type": "string", "description": "Dynamic client registration endpoint URL (RFC 7591). Optional - will be discovered from server_url if not provided.\n" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes requested. Optional - can be discovered from server_url if not provided.\nExample: [\"read\", \"write\"]\n" }, "resource": { "type": "string", "description": "Resource indicator (RFC 8707) sent on authorization and token requests.\nOptional - identifies the protected MCP resource the token is intended\nfor, when the upstream provider supports resource indicators.\n" } } }, "OAuthFlowInitiation": { "type": "object", "description": "Response when initiating an OAuth flow", "properties": { "status": { "type": "string", "enum": [ "pending_oauth" ] }, "message": { "type": "string" }, "oauth_config_id": { "type": "string", "description": "ID of the OAuth config created for this flow" }, "authorize_url": { "type": "string", "description": "URL to redirect the user to for authorization" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the OAuth authorization request expires" }, "mcp_client_id": { "type": "string", "description": "The MCP client ID that initiated this OAuth flow" }, "complete_url": { "type": "string", "description": "Relative URL to POST once the flow is authorized\n(/api/mcp/client/{oauth_config_id}/complete-oauth). Note the path\nparameter is the oauth_config_id, not the MCP client ID.\n" }, "status_url": { "type": "string", "description": "Relative URL to poll for the flow status\n(/api/oauth/config/{oauth_config_id}/status). Wait for\nstatus \"authorized\" before calling complete_url.\n" }, "next_steps": { "type": "array", "items": { "type": "string" }, "description": "Human-readable steps to complete the flow (authorize, poll, complete)" } } }, "OAuthConfigStatus": { "type": "object", "description": "Status of an OAuth configuration", "properties": { "id": { "type": "string", "description": "OAuth config ID" }, "status": { "type": "string", "enum": [ "pending", "authorized", "failed" ], "description": "Current status of the OAuth flow:\n- pending: User has not yet authorized\n- authorized: User authorized and token is stored\n- failed: Authorization failed\n" }, "created_at": { "type": "string", "format": "date-time", "description": "When this OAuth config was created" }, "token_id": { "type": "string", "description": "ID of the associated OAuth token (only present if status is authorized)" }, "token_expires_at": { "type": "string", "format": "date-time", "description": "When the OAuth access token expires (only present if status is authorized)" }, "token_scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted in the OAuth token (only present if status is authorized)" } } }, "OAuthToken": { "type": "object", "description": "OAuth access and refresh tokens", "properties": { "id": { "type": "string", "description": "Unique token identifier" }, "access_token": { "type": "string", "description": "OAuth access token" }, "refresh_token": { "type": "string", "description": "OAuth refresh token for obtaining new access tokens" }, "token_type": { "type": "string", "description": "Token type (typically \"Bearer\")" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the access token expires" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted in this token" }, "last_refreshed_at": { "type": "string", "format": "date-time", "description": "When the token was last refreshed" } } }, "MCPOauthFlowDetail": { "type": "object", "description": "Response for GET /api/oauth/per-user/flows/{id}. Mirrors the headers-side\n`MCPHeadersFlowDetail` — identity binding for display plus the bits the\nconsent UI needs to decide its copy.\n", "required": [ "id", "flow_mode", "status", "mcp_client", "oauth_config_id", "expires_at", "created_at", "has_active_token" ], "properties": { "id": { "type": "string" }, "flow_mode": { "type": "string", "enum": [ "user", "vk", "session" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "failed", "expired" ] }, "mcp_client": { "$ref": "#/components/schemas/MCPClientSummary" }, "oauth_config_id": { "type": "string" }, "user_id": { "type": "string", "nullable": true }, "user": { "$ref": "#/components/schemas/MCPUserSummary", "nullable": true }, "virtual_key": { "$ref": "#/components/schemas/MCPVirtualKeySummary", "nullable": true }, "session_id": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "has_active_token": { "type": "boolean", "description": "True when an active token already exists for the flow's binding. A\npending flow with this set means OAuth was re-initiated unnecessarily;\nthe consent page can render this as \"already authenticated\" instead\nof prompting again.\n" } } }, "MCPClientSummary": { "type": "object", "description": "Minimal MCP client view embedded in session rows.", "properties": { "client_id": { "type": "string" }, "name": { "type": "string" } } }, "MCPVirtualKeySummary": { "type": "object", "description": "Minimal virtual-key view embedded in session rows.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "MCPUserSummary": { "type": "object", "description": "Minimal user view embedded on user-keyed session rows.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "MCPSessionRow": { "type": "object", "description": "One row on the MCP Sessions list. Covers OAuth tokens, header credentials,\nand pending flows (of either kind). Always-set fields are at the top;\nper-kind-only fields use omitempty.\n", "required": [ "id", "kind", "auth_kind", "auth_mode", "status", "created_at", "can_reauth" ], "properties": { "id": { "type": "string", "description": "Row primary key — token UUID, header credential UUID, or flow UUID" }, "kind": { "type": "string", "enum": [ "token", "header", "flow" ], "description": "Row type:\n- token: completed per-user OAuth credential\n- header: completed per-user-headers credential\n- flow: pending submission / consent flow (use auth_kind to disambiguate OAuth vs Headers)\n" }, "auth_kind": { "type": "string", "enum": [ "oauth", "headers" ], "description": "Disambiguates flow rows by which auth surface they belong to. For\n`kind=token` this is always `oauth`; for `kind=header` always `headers`.\n" }, "auth_mode": { "type": "string", "enum": [ "user", "vk", "session" ], "description": "Identity dimension this credential is keyed against" }, "user_id": { "type": "string", "nullable": true, "description": "Populated on user-keyed rows; refers to the SCIM user table" }, "user": { "$ref": "#/components/schemas/MCPUserSummary", "nullable": true, "description": "Preloaded user summary; nil when the user table is not available" }, "virtual_key": { "$ref": "#/components/schemas/MCPVirtualKeySummary", "nullable": true }, "mcp_client": { "$ref": "#/components/schemas/MCPClientSummary", "nullable": true }, "session_id": { "type": "string", "nullable": true, "description": "Populated only on session-keyed rows" }, "status": { "type": "string", "enum": [ "active", "orphaned", "pending", "needs_reauth", "needs_update" ], "description": "OAuth tokens use: active | orphaned | needs_reauth.\nHeader credentials use: active | orphaned | needs_update.\nFlow rows use: pending.\n" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the OAuth access token expires; nil for header rows" }, "created_at": { "type": "string", "format": "date-time" }, "last_refreshed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "OAuth token rows only — last successful refresh" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Header credential rows only — last submission / edit" }, "oauth_config_id": { "type": "string", "nullable": true, "description": "OAuth rows only" }, "can_reauth": { "type": "boolean", "description": "Mirrors the server-side identity gate on POST /api/mcp/sessions/{id}/reauth.\nAlways true for vk- and session-mode rows. For user-mode rows, true only\nwhen the calling user matches the row's bound user — admin DAC scope is\nenough to see the row, but reauthing mints credentials under whoever clicks\nthe URL, so the server returns 403 to non-bound callers. The UI hides the\nRe-authenticate / Edit values action when this is false.\n" } } }, "MCPSessionsListResponse": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/MCPSessionRow" } } } }, "MCPSessionReauthResponse": { "type": "object", "description": "Response for POST /api/mcp/sessions/{id}/reauth. Returns the URL the caller\nmust visit to complete the fresh authentication / resubmission.\n", "required": [ "authorize_url", "session_id" ], "properties": { "authorize_url": { "type": "string", "description": "Where the caller must go. For OAuth rows this is the upstream provider's\nauthorize page (via a Bifrost intermediate). For header credential rows\nit's the Bifrost submission form for the new flow.\n" }, "submit_url": { "type": "string", "description": "Set only on header re-auth and identical to authorize_url. Kept for\ncallers that want to be explicit about the underlying surface.\n" }, "session_id": { "type": "string", "description": "ID of the freshly-minted flow row" }, "kind": { "type": "string", "enum": [ "oauth", "headers" ], "description": "Set only on header re-auth" } } }, "MCPHeadersFlowDetail": { "type": "object", "description": "Response for GET /api/mcp/per-user-headers/flows/{id}. Carries the schema\nthe end-user needs to fill in plus identity binding info for display.\n", "required": [ "id", "flow_mode", "status", "expires_at", "created_at", "required_header_keys", "has_active_credential" ], "properties": { "id": { "type": "string" }, "flow_mode": { "type": "string", "enum": [ "user", "vk", "session" ] }, "status": { "type": "string", "enum": [ "pending", "completed", "expired" ] }, "mcp_client": { "$ref": "#/components/schemas/MCPClientSummary", "nullable": true }, "user_id": { "type": "string", "nullable": true }, "user": { "$ref": "#/components/schemas/MCPUserSummary", "nullable": true }, "virtual_key": { "$ref": "#/components/schemas/MCPVirtualKeySummary", "nullable": true }, "session_id": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "required_header_keys": { "type": "array", "items": { "type": "string" }, "description": "Header names the end-user must supply on this submission" }, "admin_header_keys": { "type": "array", "items": { "type": "string" }, "description": "Names (not values) of static admin headers attached to every per-user\nrequest. Surfaced so the user understands what context will accompany\ntheir values.\n" }, "submitted_keys": { "type": "array", "items": { "type": "string" }, "description": "Names of header keys already on the caller's existing credential.\nPopulated whenever a credential exists for the binding (both `active`\nand `needs_update` states — `orphaned` credentials are filtered\nserver-side). Values are never returned. `has_active_credential` only\nflips to true when the credential is in `active` state.\n" }, "has_active_credential": { "type": "boolean", "description": "True when a credential already exists for the flow's (mode, identity,\nmcp_client) triple. The submission UI uses this to render an \"edit\"\naffordance instead of a fresh form.\n" } } }, "MCPHeadersSubmitRequest": { "type": "object", "description": "Request body for PUT /api/mcp/per-user-headers/flows/{id}. The flow row\nidentifies the (mode, identity, mcp_client) triple, so the caller carries\nonly the values. Extra keys not in the live `per_user_header_keys` schema\nare dropped server-side.\n", "required": [ "headers" ], "properties": { "headers": { "type": "object", "additionalProperties": { "type": "string" } } } }, "MCPHeadersSubmitResponse": { "type": "object", "required": [ "status", "credential_id", "updated_at" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "credential_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "VirtualKey": { "type": "object", "description": "Virtual key configuration", "required": [ "id", "name", "value", "is_active", "provider_configs", "mcp_configs", "calendar_aligned", "config_hash", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiry timestamp. Requests using this virtual key are rejected once it passes. Null or absent means the key never expires." }, "previous_value_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When set, the pre-rotation key value continues to authenticate until this timestamp (rotation grace period, configured via client vk_rotation_cooldown). Absent when no grace window is active." }, "rotated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent value rotation. Absent if the key has never been rotated." }, "provider_configs": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualKeyProviderConfig" } }, "mcp_configs": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualKeyMCPConfig" } }, "team_id": { "type": "string" }, "customer_id": { "type": "string" }, "rate_limit_id": { "type": "string" }, "calendar_aligned": { "type": "boolean" }, "team": { "$ref": "#/components/schemas/Team" }, "customer": { "$ref": "#/components/schemas/Customer" }, "budgets": { "type": "array", "description": "Budget quotas assigned directly to this virtual key", "items": { "$ref": "#/components/schemas/Budget" } }, "rate_limit": { "$ref": "#/components/schemas/RateLimit" }, "config_hash": { "type": "string" }, "created_by_user_id": { "type": "string", "description": "User that created this virtual key, when available" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "VirtualKeyResponse": { "type": "object", "description": "Virtual key operation response", "required": [ "message", "virtual_key" ], "properties": { "message": { "type": "string" }, "virtual_key": { "$ref": "#/components/schemas/VirtualKey" } } }, "VirtualKeyProviderConfig": { "type": "object", "description": "Provider configuration for a virtual key", "required": [ "id", "virtual_key_id", "provider", "weight", "allowed_models", "blacklisted_models", "allow_all_keys", "keys" ], "properties": { "id": { "type": "integer" }, "virtual_key_id": { "type": "string" }, "provider": { "type": "string" }, "weight": { "type": [ "number", "null" ], "description": "Weight for provider load balancing. Null means excluded from weighted routing." }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "blacklisted_models": { "type": "array", "items": { "type": "string" } }, "allow_all_keys": { "type": "boolean" }, "rate_limit_id": { "type": "string" }, "budgets": { "type": "array", "description": "Budget quotas assigned to this provider config", "items": { "$ref": "#/components/schemas/Budget" } }, "rate_limit": { "$ref": "#/components/schemas/RateLimit" }, "keys": { "type": [ "array", "null" ], "description": "Associated API keys for this provider config. **Always null in the quota endpoint** — keys are intentionally not loaded here to keep the response lean and avoid exposing sensitive credentials. Use the admin virtual-key API to inspect actual key assignments.\n", "items": { "$ref": "#/components/schemas/TableKey" } } } }, "VirtualKeyMCPConfig": { "type": "object", "description": "MCP configuration for a virtual key", "required": [ "id", "virtual_key_id", "mcp_client_id", "mcp_client", "tools_to_execute" ], "properties": { "id": { "type": "integer" }, "virtual_key_id": { "type": "string" }, "mcp_client_id": { "type": "integer" }, "mcp_client": { "$ref": "#/components/schemas/MCPClientConfig" }, "tools_to_execute": { "type": "array", "items": { "type": "string" } } } }, "ListVirtualKeysResponse": { "type": "object", "description": "List virtual keys response", "required": [ "virtual_keys", "count", "total_count", "limit", "offset" ], "properties": { "virtual_keys": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualKey" } }, "count": { "type": "integer" }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of virtual keys matching the query" }, "limit": { "type": "integer", "description": "Page size used for the response" }, "offset": { "type": "integer", "description": "Page offset used for the response" } } }, "VirtualKeyQuotaResponse": { "type": "object", "description": "Virtual key quota response (self-service, no admin auth required)", "required": [ "virtual_key_name", "is_active", "budgets", "rate_limit", "provider_configs", "model_configs" ], "properties": { "virtual_key_name": { "type": "string", "description": "Name of the virtual key" }, "is_active": { "type": "boolean", "description": "Whether the virtual key is active" }, "budgets": { "type": [ "array", "null" ], "description": "Overall budget quotas for this virtual key. Each budget also carries the actual per-model spend (from request logs) accumulated in its current cycle.\n", "items": { "description": "A virtual key budget with the actual per-model spend (from request logs) accumulated in its current cycle [last_reset, now]. The per-model totals reconcile with current_usage. The models list is empty when the logging plugin is not enabled.\n", "allOf": [ { "$ref": "#/components/schemas/Budget" }, { "type": "object", "required": [ "per_model_usage" ], "properties": { "per_model_usage": { "type": "array", "description": "Per-model actual usage within this budget's current cycle", "items": { "type": "object", "description": "One model's actual usage (from request logs) within a budget cycle", "required": [ "model", "total_requests", "total_tokens", "total_cost" ], "properties": { "model": { "type": "string", "description": "The model name" }, "provider": { "type": "string", "description": "Provider that served the model; omitted when unknown" }, "total_requests": { "type": "integer", "format": "int64", "description": "Number of requests to this model in the cycle" }, "total_tokens": { "type": "integer", "format": "int64", "description": "Total tokens consumed by this model in the cycle" }, "total_cost": { "type": "number", "description": "Total cost in dollars for this model in the cycle" } } } } } } ] } }, "rate_limit": { "oneOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "null" } ] }, "provider_configs": { "type": [ "array", "null" ], "description": "Per-provider budget quotas and rate limits (provider-level splits and limits)", "items": { "$ref": "#/components/schemas/VirtualKeyProviderConfig" } }, "model_configs": { "type": "array", "description": "Per-model budget quotas and rate limits configured for this virtual key (model-level limits). Always an array — the endpoint fails closed (500) rather than returning null when the model-config lookup errors.\n", "items": { "type": "object", "description": "Per-model budgets and rate limit (with current usage) for a model governed under a virtual key", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "The model this usage applies to" }, "provider": { "type": "string", "description": "Provider this model config is scoped to; omitted when it applies to all providers" }, "budgets": { "type": [ "array", "null" ], "description": "Budget quotas for this model", "items": { "$ref": "#/components/schemas/Budget" } }, "rate_limit": { "oneOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "null" } ] } } } } } }, "CreateVirtualKeyRequest": { "type": "object", "description": "Create virtual key request", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "provider_configs": { "type": "array", "description": "Provider configurations (empty means no providers allowed, deny-by-default)", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "weight": { "type": [ "number", "null" ], "description": "Weight for load balancing. Null means excluded from weighted routing." }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "blacklisted_models": { "type": "array", "items": { "type": "string" } }, "budgets": { "type": "array", "description": "Provider-specific budget quotas", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/CreateRateLimitRequest" }, "key_ids": { "type": "array", "items": { "type": "string" } } } } }, "mcp_configs": { "type": "array", "description": "MCP configurations (empty means no MCP tools allowed, deny-by-default)", "items": { "type": "object", "properties": { "mcp_client_name": { "type": "string" }, "tools_to_execute": { "type": "array", "items": { "type": "string" } } } } }, "team_id": { "type": "string" }, "customer_id": { "type": "string" }, "budgets": { "type": "array", "description": "Budget quotas assigned directly to this virtual key", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/CreateRateLimitRequest" }, "is_active": { "type": "boolean" }, "calendar_aligned": { "type": "boolean", "default": false }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional expiry timestamp. Must be in the future. Omit for a key that never expires." } } }, "UpdateVirtualKeyRequest": { "type": "object", "description": "Update virtual key request", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "provider_configs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "provider": { "type": "string" }, "weight": { "type": [ "number", "null" ], "description": "Weight for load balancing. Null means excluded from weighted routing." }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "blacklisted_models": { "type": "array", "items": { "type": "string" } }, "budgets": { "type": "array", "description": "Provider-specific budget quotas. Replaces all budgets for that provider config when provided.", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/UpdateRateLimitRequest" }, "key_ids": { "type": "array", "items": { "type": "string" } } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "mcp_client_name": { "type": "string" }, "tools_to_execute": { "type": "array", "items": { "type": "string" } } } } }, "team_id": { "type": "string" }, "customer_id": { "type": "string" }, "budgets": { "type": "array", "description": "Budget quotas assigned directly to this virtual key. Replaces all direct virtual-key budgets when provided.", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/UpdateRateLimitRequest" }, "is_active": { "type": "boolean" }, "calendar_aligned": { "type": "boolean" }, "reset_budget_usage": { "type": "boolean", "description": "When true, zeroes current usage on the budgets reconciled by this update. The reset window is left alone: last_reset only ever advances, and never as a side effect of a configuration write, so the current window keeps its existing start and end.\n" }, "expires_at": { "type": "string", "description": "RFC3339 timestamp to set a new expiry (must be in the future), empty string to clear an existing expiry, omitted to leave it unchanged." } } }, "Team": { "type": "object", "description": "Team configuration", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "customer_id": { "type": "string" }, "customer": { "$ref": "#/components/schemas/Customer" }, "budgets": { "type": "array", "description": "Budgets owned by this team", "items": { "$ref": "#/components/schemas/Budget" } }, "virtual_keys": { "type": [ "array", "null" ], "description": "Virtual keys assigned to this team. This field may be omitted or returned as null in some responses (for example, when a team is embedded inside a virtual-key response) to avoid nested `virtual_keys` recursion.\n", "items": { "$ref": "#/components/schemas/VirtualKey" } }, "profile": { "type": "object", "additionalProperties": true }, "config": { "type": "object", "additionalProperties": true }, "claims": { "type": "object", "additionalProperties": true }, "config_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TeamResponse": { "type": "object", "description": "Team operation response", "properties": { "message": { "type": "string" }, "team": { "$ref": "#/components/schemas/Team" } } }, "ListTeamsResponse": { "type": "object", "description": "List teams response", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "count": { "type": "integer" } } }, "CreateTeamRequest": { "type": "object", "description": "Create team request", "required": [ "name" ], "properties": { "name": { "type": "string" }, "customer_id": { "type": "string" }, "budgets": { "type": "array", "description": "Budgets to create for this team; reset durations must be unique", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } } } }, "UpdateTeamRequest": { "type": "object", "description": "Update team request", "properties": { "name": { "type": "string" }, "customer_id": { "type": "string" }, "budgets": { "type": "array", "description": "Replacement set of budgets for this team; reset durations must be unique", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "reset_budget_usage": { "type": "boolean", "description": "When true, zeroes current usage on the budgets reconciled by this update. The reset window is left alone: last_reset only ever advances, and never as a side effect of a configuration write, so the current window keeps its existing start and end.\n" } } }, "Customer": { "type": "object", "description": "Customer configuration", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "budget_id": { "type": "string" }, "budget": { "$ref": "#/components/schemas/Budget" }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "virtual_keys": { "type": [ "array", "null" ], "description": "Virtual keys owned by this customer. Omitted or returned as null by the paginated list endpoint (`GET /api/governance/customers` with `limit`/`offset`/`search`), which reports `virtual_key_count` instead; use the single-customer endpoint to retrieve the keys themselves.\n", "items": { "$ref": "#/components/schemas/VirtualKey" } }, "virtual_key_count": { "type": "integer", "description": "Number of virtual keys owned by this customer. Always populated." }, "config_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CustomerResponse": { "type": "object", "description": "Customer operation response", "properties": { "message": { "type": "string" }, "customer": { "$ref": "#/components/schemas/Customer" } } }, "ListCustomersResponse": { "type": "object", "description": "List customers response", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "count": { "type": "integer" } } }, "CreateCustomerRequest": { "type": "object", "description": "Create customer request", "required": [ "name" ], "properties": { "name": { "type": "string" }, "budget": { "$ref": "#/components/schemas/CreateBudgetRequest" } } }, "UpdateCustomerRequest": { "type": "object", "description": "Update customer request", "properties": { "name": { "type": "string" }, "budget": { "$ref": "#/components/schemas/UpdateBudgetRequest" }, "reset_budget_usage": { "type": "boolean", "description": "When true, zeroes current usage on the budgets reconciled by this update. The reset window is left alone: last_reset only ever advances, and never as a side effect of a configuration write, so the current window keeps its existing start and end.\n" } } }, "Budget": { "type": "object", "description": "Budget configuration", "required": [ "id", "max_limit", "reset_duration", "last_reset", "current_usage", "config_hash", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "max_limit": { "type": "number", "description": "Maximum budget in dollars" }, "reset_duration": { "type": "string", "description": "Reset duration (e.g., \"30s\", \"5m\", \"1h\", \"1d\", \"1w\", \"1M\", \"1Q\")" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.\n", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1.\n" } }, "additionalProperties": false }, "calendar_aligned": { "type": "boolean", "description": "When true, resets align to calendar period boundaries in UTC (not rolling from last reset)", "default": false }, "last_reset": { "type": "string", "format": "date-time" }, "current_usage": { "type": "number" }, "override_amount": { "type": "number", "description": "Additional spend added on top of `max_limit` while the override is active. Omitted when no override is set." }, "override_mode": { "type": "string", "description": "How long the override stays active. `cycles` keeps it active for a finite number of\nreset windows; `forever` keeps it active until it is removed. Omitted when no override is set.\n", "enum": [ "cycles", "forever" ] }, "override_cycles_remaining": { "type": "integer", "description": "Reset windows the override is still valid for, including the current one. Positive only\nfor `cycles` mode; recomputed from the original grant on every reset, never decremented in place.\n" }, "override_cycles_total": { "type": "integer", "description": "Number of reset windows the current `cycles` override was granted for. Immutable for the life of the grant." }, "override_anchor_reset": { "type": "string", "format": "date-time", "description": "Reset-window boundary at which the current `cycles` override was granted. Immutable for the life of the grant." }, "team_id": { "type": "string", "description": "Team that owns this budget, when the budget is team-scoped" }, "virtual_key_id": { "type": "string", "description": "Virtual key that owns this budget, when the budget is virtual-key-scoped" }, "provider_config_id": { "type": "integer", "description": "Provider config that owns this budget, when the budget is provider-config-scoped" }, "config_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RateLimit": { "type": "object", "description": "Rate limit configuration", "required": [ "id", "token_current_usage", "token_last_reset", "request_current_usage", "request_last_reset", "config_hash", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "token_max_limit": { "type": "integer", "format": "int64" }, "token_reset_duration": { "type": "string" }, "token_current_usage": { "type": "integer", "format": "int64" }, "token_last_reset": { "type": "string", "format": "date-time" }, "request_max_limit": { "type": [ "integer", "null" ], "format": "int64" }, "request_reset_duration": { "type": [ "string", "null" ] }, "request_current_usage": { "type": "integer", "format": "int64" }, "request_last_reset": { "type": "string", "format": "date-time" }, "config_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ListBudgetsResponse": { "type": "object", "description": "List budgets response", "properties": { "budgets": { "type": "array", "items": { "$ref": "#/components/schemas/Budget" } }, "count": { "type": "integer" } } }, "ListRateLimitsResponse": { "type": "object", "description": "List rate limits response", "properties": { "rate_limits": { "type": "array", "items": { "$ref": "#/components/schemas/RateLimit" } }, "count": { "type": "integer" } } }, "CreateBudgetRequest": { "type": "object", "description": "Create budget request", "required": [ "max_limit", "reset_duration" ], "properties": { "max_limit": { "type": "number" }, "reset_duration": { "type": "string" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.\n", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1.\n" } }, "additionalProperties": false }, "calendar_aligned": { "type": "boolean", "default": false, "description": "When true, usage resets at the start of each calendar period in UTC instead of on a rolling window from last reset. Only valid with reset durations that use day, week, month, quarter, or year suffixes (`d`, `w`, `M`, `Q`, `Y`). For example `1d` resets at midnight UTC; `1w` at Monday 00:00 UTC; `1M` on the first day of each month; `1Q` on the first day of the fiscal quarter; `1Y` on January 1. Sub-day durations (e.g. `1h`) cannot use calendar alignment.\n" } } }, "UpdateBudgetRequest": { "type": "object", "description": "Update budget request", "properties": { "max_limit": { "type": "number" }, "reset_duration": { "type": "string" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when reset_duration is quarterly (`1Q`); the API rejects it on any other window.\n", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12, so a fiscal year opening in April (4) gives Apr-Jun / Jul-Sep / Oct-Dec / Jan-Mar. Omitted means January. Quarter boundaries repeat every three months, so only the value modulo 3 changes the reset dates: January, April, July and October all reset on calendar quarters and differ only in which quarter is labelled Q1.\n" } }, "additionalProperties": false }, "calendar_aligned": { "type": [ "boolean", "null" ], "description": "Set to true or false to enable or disable calendar-aligned resets. Only valid with reset durations that use day, week, month, quarter, or year suffixes (`d`, `w`, `M`, `Q`, `Y`); sub-day durations (e.g. `1h`, `30m`) are invalid with calendar alignment and the API rejects that combination. When enabling on an existing budget, alignment takes effect from the next period: the current window keeps its start and its accumulated usage, and the first aligned reset happens at the next boundary. Changing quarter_start_month on a calendar-aligned quarterly budget does not move last_reset directly; the new definition shifts where the current window starts, so the budget converges onto the new fiscal boundary on the next reset tick.\n" } } }, "BudgetOverrideRequest": { "type": "object", "description": "Replaces the active override on one budget. The override is additive: it does not change the\nbudget's `max_limit`, `current_usage`, or reset schedule. Sending this request against a budget\nthat already has an override replaces that override entirely.\n", "required": [ "amount", "mode" ], "properties": { "amount": { "type": "number", "description": "Additional spend in dollars added on top of `max_limit` while the override is active. Must be greater than 0 and finite." }, "mode": { "type": "string", "description": "`cycles` keeps the override active for `cycles` reset windows starting with the current one.\n`forever` keeps it active until it is removed with a DELETE.\n", "enum": [ "cycles", "forever" ] }, "cycles": { "type": "integer", "description": "Number of reset windows the override stays active for, counting the current window as the first.\nRequired and must be greater than 0 when `mode` is `cycles`; must be omitted or 0 when `mode` is `forever`.\n", "minimum": 1 } } }, "BudgetOverrideResponse": { "type": "object", "description": "The persisted budget and the additive limit now in force.", "required": [ "budget", "effective_max_limit" ], "properties": { "budget": { "$ref": "#/components/schemas/Budget" }, "effective_max_limit": { "type": "number", "description": "`max_limit` plus `override_amount` while an override is active; equal to `max_limit` otherwise." } } }, "CreateRateLimitRequest": { "type": "object", "description": "Create rate limit request", "properties": { "token_max_limit": { "type": "integer", "format": "int64" }, "token_reset_duration": { "type": "string" }, "request_max_limit": { "type": "integer", "format": "int64" }, "request_reset_duration": { "type": "string" } } }, "UpdateRateLimitRequest": { "type": "object", "description": "Update rate limit request", "properties": { "token_max_limit": { "type": "integer", "format": "int64" }, "token_reset_duration": { "type": "string" }, "request_max_limit": { "type": "integer", "format": "int64" }, "request_reset_duration": { "type": "string" } } }, "RoutingRule": { "type": "object", "description": "CEL-based routing rule for intelligent request routing", "properties": { "id": { "type": "string", "description": "Unique identifier for the routing rule" }, "name": { "type": "string", "description": "Name of the routing rule" }, "description": { "type": "string", "description": "Description of what the rule does" }, "enabled": { "type": "boolean", "description": "Whether the rule is enabled and active" }, "cel_expression": { "type": "string", "description": "CEL (Common Expression Language) expression for matching" }, "targets": { "type": "array", "description": "Weighted routing targets; weights must sum to 1; target is selected probabilistically at request time", "items": { "type": "object", "description": "A single weighted routing target within a routing rule", "required": [ "weight" ], "dependentRequired": { "key_id": [ "provider" ] }, "properties": { "provider": { "type": [ "string", "null" ], "description": "Target provider (omit or empty to use the incoming request provider)" }, "model": { "type": [ "string", "null" ], "description": "Target model (omit or empty to use the incoming request model)" }, "key_id": { "type": [ "string", "null" ], "description": "UUID of the API key to pin for this target (omit for load-balanced key selection)" }, "weight": { "type": "number", "format": "double", "exclusiveMinimum": 0, "description": "Probability weight for this target (must be > 0; all target weights in a rule must sum to 1, e.g. 0.7 + 0.3 = 1.0)", "example": 0.5 } } } }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback providers in format \"provider/model\"" }, "scope": { "type": "string", "enum": [ "global", "team", "customer", "virtual_key" ], "description": "Scope level for the rule" }, "scope_id": { "type": [ "string", "null" ], "description": "ID for the scope (empty for global scope)" }, "priority": { "type": "integer", "description": "Priority for rule evaluation (lower number = higher priority)" }, "query": { "type": [ "object", "null" ], "description": "Visual rule tree structure from query builder" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "global" ] } }, "required": [ "scope" ], "description": "Global scope routing rule" }, { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "team", "customer", "virtual_key" ] }, "scope_id": { "type": "string" } }, "required": [ "scope", "scope_id" ], "description": "Scoped routing rule (requires scope_id)" } ] }, "RoutingRuleResponse": { "type": "object", "description": "Response containing created/updated routing rule", "properties": { "message": { "type": "string" }, "rule": { "$ref": "#/components/schemas/RoutingRule" } } }, "ListRoutingRulesResponse": { "type": "object", "description": "Response containing list of routing rules", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingRule" } }, "count": { "type": "integer", "description": "Number of routing rules returned" } } }, "CreateRoutingRuleRequest": { "type": "object", "description": "Request to create a routing rule", "required": [ "name", "cel_expression", "scope", "priority", "targets" ], "properties": { "name": { "type": "string", "description": "Name of the routing rule" }, "description": { "type": "string", "description": "Optional description" }, "enabled": { "type": "boolean", "description": "Whether the rule is enabled" }, "cel_expression": { "type": "string", "description": "CEL expression for matching" }, "targets": { "type": "array", "minItems": 1, "description": "Weighted routing targets; weights must sum to 1; target is selected probabilistically at request time", "items": { "type": "object", "description": "A single weighted routing target within a routing rule", "required": [ "weight" ], "dependentRequired": { "key_id": [ "provider" ] }, "properties": { "provider": { "type": [ "string", "null" ], "description": "Target provider (omit or empty to use the incoming request provider)" }, "model": { "type": [ "string", "null" ], "description": "Target model (omit or empty to use the incoming request model)" }, "key_id": { "type": [ "string", "null" ], "description": "UUID of the API key to pin for this target (omit for load-balanced key selection)" }, "weight": { "type": "number", "format": "double", "exclusiveMinimum": 0, "description": "Probability weight for this target (must be > 0; all target weights in a rule must sum to 1, e.g. 0.7 + 0.3 = 1.0)", "example": 0.5 } } } }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback providers in format \"provider/model\"" }, "scope": { "type": "string", "enum": [ "global", "team", "customer", "virtual_key" ], "description": "Scope level for the rule" }, "scope_id": { "type": [ "string", "null" ], "description": "ID for the scope (required if scope is not global)" }, "priority": { "type": "integer", "description": "Priority for rule evaluation (lower number = higher priority)" }, "query": { "type": [ "object", "null" ], "description": "Visual rule tree structure" } }, "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "global" ] } }, "required": [ "scope" ], "description": "Global scope routing rule" }, { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "team", "customer", "virtual_key" ] }, "scope_id": { "type": "string" } }, "required": [ "scope", "scope_id" ], "description": "Scoped routing rule (requires scope_id)" } ] }, "UpdateRoutingRuleRequest": { "type": "object", "description": "Request to update a routing rule (all fields optional; providing `targets` replaces all existing targets)", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "cel_expression": { "type": "string" }, "targets": { "type": "array", "minItems": 1, "description": "Replaces all existing targets when provided; weights must sum to 1", "items": { "type": "object", "description": "A single weighted routing target within a routing rule", "required": [ "weight" ], "dependentRequired": { "key_id": [ "provider" ] }, "properties": { "provider": { "type": [ "string", "null" ], "description": "Target provider (omit or empty to use the incoming request provider)" }, "model": { "type": [ "string", "null" ], "description": "Target model (omit or empty to use the incoming request model)" }, "key_id": { "type": [ "string", "null" ], "description": "UUID of the API key to pin for this target (omit for load-balanced key selection)" }, "weight": { "type": "number", "format": "double", "exclusiveMinimum": 0, "description": "Probability weight for this target (must be > 0; all target weights in a rule must sum to 1, e.g. 0.7 + 0.3 = 1.0)", "example": 0.5 } } } }, "fallbacks": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "integer" }, "query": { "type": [ "object", "null" ] } } }, "TableKey": { "type": "object", "description": "Table key configuration", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "provider_id": { "type": "integer" }, "provider": { "type": "string" }, "key_id": { "type": "string" }, "value": { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, "models": { "type": "array", "items": { "type": "string" } }, "weight": { "type": [ "number", "null" ] }, "enabled": { "type": [ "boolean", "null" ], "default": true }, "use_for_batch_api": { "type": [ "boolean", "null" ], "default": false }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "config_hash": { "type": [ "string", "null" ] }, "azure_endpoint": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "azure_client_id": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "azure_client_secret": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "azure_tenant_id": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "vertex_project_id": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "vertex_project_number": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "vertex_region": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "vertex_auth_credentials": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "bedrock_access_key": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "bedrock_secret_key": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "bedrock_session_token": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "bedrock_region": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] }, "bedrock_arn": { "oneOf": [ { "type": "object", "description": "A secret-capable value. Serialized as an object with the resolved `value` plus\nreference metadata; on input, a bare string is also accepted — plain text,\n`env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and\nonly the reference is persisted).\n", "properties": { "value": { "type": "string", "description": "Resolved value (redacted in GET responses for secret fields)" }, "ref": { "type": "string", "description": "Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values" }, "type": { "type": "string", "enum": [ "plain_text", "env", "vault" ], "description": "Source type of the value" } } }, { "type": "null" } ] } } }, "ModelConfig": { "type": "object", "description": "Model configuration with budget and rate limit settings", "properties": { "id": { "type": "string", "description": "Unique identifier for the model config" }, "model_name": { "type": "string", "description": "Name of the model. Use `*` to match all models." }, "provider": { "type": "string", "description": "Provider name (optional - applies to all providers if not specified)" }, "scope": { "type": "string", "description": "Scope where this limit applies. `global` covers all traffic; `virtual_key` scopes to a single virtual key; `user` scopes to a single user (Enterprise only).", "enum": [ "global", "virtual_key", "user" ], "default": "global" }, "scope_id": { "type": "string", "nullable": true, "description": "ID of the scope target (e.g. virtual key ID or user ID). Required when scope is not `global`." }, "scope_name": { "type": "string", "nullable": true, "description": "Resolved human-readable name of the scope target (read-only, set by server)." }, "calendar_aligned": { "type": "boolean", "description": "When true, all budgets reset at clean calendar boundaries (midnight UTC for day, Monday for week, 1st for month, Jan 1 for year).", "default": false }, "budgets": { "type": "array", "description": "Budget configurations for this model limit. Each entry must have a unique reset_duration.", "items": { "$ref": "#/components/schemas/Budget" } }, "budget": { "$ref": "#/components/schemas/Budget", "description": "Deprecated: use `budgets`. Returns the first budget for backward compatibility." }, "rate_limit": { "$ref": "#/components/schemas/RateLimit", "description": "Rate limit configuration for this model" }, "created_at": { "type": "string", "format": "date-time", "description": "When this model config was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When this model config was last updated" } } }, "ModelConfigResponse": { "type": "object", "description": "Response containing a created/updated model config", "properties": { "message": { "type": "string" }, "model_config": { "$ref": "#/components/schemas/ModelConfig" } } }, "ListModelConfigsResponse": { "type": "object", "description": "Response containing list of model configs", "properties": { "model_configs": { "type": "array", "items": { "$ref": "#/components/schemas/ModelConfig" } }, "total_count": { "type": "integer", "description": "Total number of model configs matching the filter (used for pagination)" } } }, "CreateModelConfigRequest": { "type": "object", "description": "Request to create a new model config", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "Name of the model (required). Use `*` to match all models." }, "provider": { "type": "string", "description": "Provider name (optional - applies to all providers if not specified)" }, "scope": { "type": "string", "description": "Scope where this limit applies. Defaults to `global`.", "enum": [ "global", "virtual_key", "user" ], "default": "global" }, "scope_id": { "type": "string", "description": "ID of the scope target (e.g. virtual key ID or user ID). Required when scope is not `global`." }, "budgets": { "type": "array", "description": "Budget lines for this limit. Each entry must have a unique reset_duration.", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/CreateRateLimitRequest", "description": "Rate limit configuration" } } }, "UpdateModelConfigRequest": { "type": "object", "description": "Request to update an existing model config. Scope and scope_id are identity fields and cannot be changed.", "properties": { "model_name": { "type": "string", "description": "Name of the model" }, "provider": { "type": "string", "description": "Provider name" }, "budgets": { "type": "array", "description": "Full desired set of budgets (reconciled server-side). Send an empty array to remove all budgets.", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/UpdateRateLimitRequest", "description": "Rate limit configuration" }, "reset_budget_usage": { "type": "boolean", "description": "When true, zeroes current usage on the budgets reconciled by this update. The reset window is left alone: last_reset only ever advances, and never as a side effect of a configuration write, so the current window keeps its existing start and end.\n" } } }, "ProviderGovernance": { "type": "object", "description": "Provider-level governance settings (budget and rate limits)", "properties": { "provider": { "type": "string", "description": "Provider name" }, "budget": { "$ref": "#/components/schemas/Budget", "description": "Budget configuration for this provider" }, "rate_limit": { "$ref": "#/components/schemas/RateLimit", "description": "Rate limit configuration for this provider" } } }, "ProviderGovernanceResponse": { "type": "object", "description": "Response containing provider governance settings", "properties": { "provider": { "type": "string", "description": "Provider name" }, "budgets": { "type": "array", "description": "Budget configurations for this provider. Each entry has a unique reset_duration.", "items": { "$ref": "#/components/schemas/Budget" } }, "budget": { "$ref": "#/components/schemas/Budget", "description": "Deprecated: use `budgets`. Returns the first budget for backward compatibility." }, "rate_limit": { "$ref": "#/components/schemas/RateLimit", "description": "Rate limit configuration" }, "calendar_aligned": { "type": "boolean", "description": "When true, all budgets reset at clean calendar boundaries (midnight UTC for day, Monday for week, 1st for month, Jan 1 for year).", "default": false } } }, "ListProviderGovernanceResponse": { "type": "object", "description": "Response containing list of provider governance settings", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderGovernanceResponse" } }, "count": { "type": "integer", "description": "Number of providers with governance settings" } } }, "UpdateProviderGovernanceRequest": { "type": "object", "description": "Request to update provider governance settings", "properties": { "budgets": { "type": "array", "nullable": true, "description": "Full desired set of budgets. Pointer-to-slice semantics apply: omitting the field leaves budgets unchanged; sending an empty array `[]` removes all budgets; sending a non-empty array replaces all existing budgets with the provided set.\n", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "budget": { "$ref": "#/components/schemas/UpdateBudgetRequest", "description": "Deprecated: use `budgets`." }, "rate_limit": { "$ref": "#/components/schemas/UpdateRateLimitRequest", "description": "Rate limit configuration" }, "calendar_aligned": { "type": "boolean", "nullable": true, "description": "When true, all budgets reset at clean calendar boundaries. Omit to leave unchanged." }, "reset_budget_usage": { "type": "boolean", "description": "When true, zeroes current usage on the budgets reconciled by this update. The reset window is left alone: last_reset only ever advances, and never as a side effect of a configuration write, so the current window keeps its existing start and end.\n" } } }, "PricingOverrideScopeKind": { "type": "string", "description": "Scope that determines which requests a pricing override applies to. The virtual_key* family is checked before the user* family during cost resolution, which is checked before the provider/global scopes; within a family, more identifiers present means a more specific match.\n", "enum": [ "global", "provider", "provider_key", "virtual_key", "virtual_key_provider", "virtual_key_provider_key", "user", "user_provider", "user_provider_key" ] }, "PricingOverrideRequestType": { "type": "string", "description": "Request type for pricing override filtering. Stream variants are treated identically to their base type - specifying `chat_completion` covers both streaming and non-streaming chat requests.\n", "enum": [ "chat_completion", "text_completion", "responses", "embedding", "rerank", "speech", "transcription", "image_generation", "image_variation", "image_edit", "video_generation", "video_remix" ] }, "PricingPatch": { "type": "object", "description": "Pricing fields to override. All non-null fields are applied. Usage-based values are costs per unit in USD. cost_per_request is a flat fee in USD applied once per billed request.\n", "properties": { "input_cost_per_token": { "type": "number", "minimum": 0 }, "output_cost_per_token": { "type": "number", "minimum": 0 }, "input_cost_per_token_batches": { "type": "number", "minimum": 0 }, "output_cost_per_token_batches": { "type": "number", "minimum": 0 }, "input_cost_per_token_priority": { "type": "number", "minimum": 0 }, "output_cost_per_token_priority": { "type": "number", "minimum": 0 }, "input_cost_per_token_flex": { "type": "number", "minimum": 0 }, "output_cost_per_token_flex": { "type": "number", "minimum": 0 }, "input_cost_per_token_fast": { "type": "number", "minimum": 0, "description": "Fast mode (Anthropic research preview). Flat rate across the full context window - no 128k/200k/272k tiering." }, "output_cost_per_token_fast": { "type": "number", "minimum": 0, "description": "Fast mode (Anthropic research preview). Flat rate across the full context window - no 128k/200k/272k tiering." }, "input_cost_per_character": { "type": "number", "minimum": 0 }, "input_cost_per_token_above_128k_tokens": { "type": "number", "minimum": 0 }, "input_cost_per_image_above_128k_tokens": { "type": "number", "minimum": 0 }, "input_cost_per_video_per_second_above_128k_tokens": { "type": "number", "minimum": 0 }, "input_cost_per_audio_per_second_above_128k_tokens": { "type": "number", "minimum": 0 }, "output_cost_per_token_above_128k_tokens": { "type": "number", "minimum": 0 }, "input_cost_per_token_above_200k_tokens": { "type": "number", "minimum": 0 }, "input_cost_per_token_above_200k_tokens_priority": { "type": "number", "minimum": 0 }, "output_cost_per_token_above_200k_tokens": { "type": "number", "minimum": 0 }, "output_cost_per_token_above_200k_tokens_priority": { "type": "number", "minimum": 0 }, "input_cost_per_token_above_272k_tokens": { "type": "number", "minimum": 0 }, "input_cost_per_token_above_272k_tokens_priority": { "type": "number", "minimum": 0 }, "input_cost_per_token_flex_above_272k_tokens": { "type": "number", "minimum": 0 }, "output_cost_per_token_above_272k_tokens": { "type": "number", "minimum": 0 }, "output_cost_per_token_above_272k_tokens_priority": { "type": "number", "minimum": 0 }, "output_cost_per_token_flex_above_272k_tokens": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost": { "type": "number", "minimum": 0 }, "cache_read_input_token_cost": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_above_200k_tokens": { "type": "number", "minimum": 0 }, "cache_read_input_token_cost_above_200k_tokens": { "type": "number", "minimum": 0 }, "cache_read_input_token_cost_above_200k_tokens_priority": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_above_1hr": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_above_1hr_above_200k_tokens": { "type": "number", "minimum": 0 }, "cache_creation_input_audio_token_cost": { "type": "number", "minimum": 0 }, "cache_read_input_token_cost_priority": { "type": "number", "minimum": 0 }, "cache_read_input_token_cost_flex": { "type": "number", "minimum": 0 }, "cache_read_input_image_token_cost": { "type": "number", "minimum": 0 }, "cache_read_input_token_cost_above_272k_tokens": { "type": "number", "minimum": 0 }, "cache_read_input_token_cost_above_272k_tokens_priority": { "type": "number", "minimum": 0 }, "cache_read_input_token_cost_flex_above_272k_tokens": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_above_272k_tokens": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_flex": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_flex_above_272k_tokens": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_priority": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_fast": { "type": "number", "minimum": 0, "description": "Fast mode (Anthropic) cache rate - flat across the full context window, no tiering." }, "cache_creation_input_token_cost_above_1hr_fast": { "type": "number", "minimum": 0, "description": "Fast mode (Anthropic) cache rate - flat across the full context window, no tiering." }, "cache_read_input_token_cost_fast": { "type": "number", "minimum": 0, "description": "Fast mode (Anthropic) cache rate - flat across the full context window, no tiering." }, "input_cost_per_image": { "type": "number", "minimum": 0 }, "input_cost_per_pixel": { "type": "number", "minimum": 0 }, "output_cost_per_image": { "type": "number", "minimum": 0 }, "output_cost_per_pixel": { "type": "number", "minimum": 0 }, "output_cost_per_image_premium_image": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_512_and_512_pixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_512_and_512_pixels_and_premium_image": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1024_pixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1024_pixels_and_premium_image": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1536_pixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1536_and_1024_pixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_2048_and_2048_pixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_4096_and_4096_pixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_4_megapixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_8_megapixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_16_megapixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_32_megapixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_64_megapixels": { "type": "number", "minimum": 0 }, "output_cost_per_image_low_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_medium_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_high_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_auto_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1024_pixels_low_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1536_pixels_low_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1536_and_1024_pixels_low_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1024_pixels_medium_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1536_pixels_medium_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1536_and_1024_pixels_medium_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1024_pixels_high_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1536_pixels_high_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1536_and_1024_pixels_high_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1024_pixels_standard_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1024_and_1536_pixels_standard_quality": { "type": "number", "minimum": 0 }, "output_cost_per_image_above_1536_and_1024_pixels_standard_quality": { "type": "number", "minimum": 0 }, "input_cost_per_image_token": { "type": "number", "minimum": 0 }, "output_cost_per_image_token": { "type": "number", "minimum": 0 }, "input_cost_per_audio_token": { "type": "number", "minimum": 0 }, "input_cost_per_audio_per_second": { "type": "number", "minimum": 0 }, "input_cost_per_second": { "type": "number", "minimum": 0 }, "input_cost_per_video_per_second": { "type": "number", "minimum": 0 }, "output_cost_per_audio_token": { "type": "number", "minimum": 0 }, "output_cost_per_video_per_second": { "type": "number", "minimum": 0 }, "output_cost_per_second": { "type": "number", "minimum": 0 }, "search_context_cost_per_query": { "type": "number", "minimum": 0 }, "input_cost_per_query": { "type": "number", "minimum": 0, "description": "Per-query rate for rerank models. One query covers up to 100 document chunks, so a request over that many chunks bills as several queries." }, "code_interpreter_cost_per_session": { "type": "number", "minimum": 0 }, "inference_geo_us_multiplier": { "type": "number", "minimum": 0, "description": "Anthropic data-residency multiplier applied when usage.inference_geo == \"us\"." }, "cost_per_request": { "type": "number", "minimum": 0, "description": "Flat fee added once per billed request, on top of any usage-based cost." }, "ocr_cost_per_page": { "type": "number", "minimum": 0 }, "annotation_cost_per_page": { "type": "number", "minimum": 0 } } }, "PricingOverride": { "type": "object", "description": "A pricing override that applies custom rates to matching requests.", "properties": { "id": { "type": "string", "description": "Unique override ID (UUID)" }, "name": { "type": "string", "description": "Human-readable label" }, "scope_kind": { "$ref": "#/components/schemas/PricingOverrideScopeKind" }, "user_id": { "type": [ "string", "null" ], "description": "Required for user* scopes" }, "virtual_key_id": { "type": [ "string", "null" ], "description": "Required for virtual_key* scopes" }, "provider_id": { "type": [ "string", "null" ], "description": "Required for provider, virtual_key_provider, and user_provider scopes" }, "provider_key_id": { "type": [ "string", "null" ], "description": "Required for provider_key, virtual_key_provider_key, and user_provider_key scopes" }, "match_type": { "type": "string", "enum": [ "exact", "wildcard" ], "description": "How the pattern is matched against the model name" }, "pattern": { "type": "string", "description": "Model name or wildcard prefix (e.g. \"gpt-4o\" or \"claude-3*\")" }, "request_types": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PricingOverrideRequestType" }, "description": "Request types this override applies to. At least one value is required." }, "pricing_patch": { "type": "string", "description": "JSON-encoded pricing fields to override (as stored in the database)" }, "patch": { "$ref": "#/components/schemas/PricingPatch", "description": "Decoded pricing fields (present in API responses)" }, "config_hash": { "type": [ "string", "null" ], "description": "Auto-managed hash for config-file-sourced overrides. Do not set manually." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreatePricingOverrideRequest": { "type": "object", "description": "Request body for creating a pricing override.", "required": [ "name", "scope_kind", "match_type", "pattern", "request_types" ], "properties": { "name": { "type": "string", "description": "Human-readable label" }, "scope_kind": { "$ref": "#/components/schemas/PricingOverrideScopeKind" }, "user_id": { "type": "string", "description": "Required for user* scopes" }, "virtual_key_id": { "type": "string", "description": "Required for virtual_key* scopes" }, "provider_id": { "type": "string", "description": "Required for provider, virtual_key_provider, and user_provider scopes" }, "provider_key_id": { "type": "string", "description": "Required for provider_key, virtual_key_provider_key, and user_provider_key scopes" }, "match_type": { "type": "string", "enum": [ "exact", "wildcard" ] }, "pattern": { "type": "string", "description": "Model name or wildcard prefix ending with * (e.g. \"claude-3*\")" }, "request_types": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PricingOverrideRequestType" }, "description": "Request types this override applies to. At least one value is required." }, "patch": { "$ref": "#/components/schemas/PricingPatch" } } }, "UpdatePricingOverrideRequest": { "type": "object", "description": "Request body for updating a pricing override. All fields are optional - omitted fields are merged from the existing record. The `patch` field is always replaced in full when provided.\n", "properties": { "name": { "type": "string", "description": "Human-readable label" }, "scope_kind": { "$ref": "#/components/schemas/PricingOverrideScopeKind" }, "user_id": { "type": "string", "description": "Required for user* scopes" }, "virtual_key_id": { "type": "string", "description": "Required for virtual_key* scopes" }, "provider_id": { "type": "string", "description": "Required for provider, virtual_key_provider, and user_provider scopes" }, "provider_key_id": { "type": "string", "description": "Required for provider_key, virtual_key_provider_key, and user_provider_key scopes" }, "match_type": { "type": "string", "enum": [ "exact", "wildcard" ] }, "pattern": { "type": "string", "description": "Model name or wildcard prefix ending with * (e.g. \"claude-3*\")" }, "request_types": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PricingOverrideRequestType" }, "description": "Request types this override applies to." }, "patch": { "$ref": "#/components/schemas/PricingPatch" } } }, "PricingOverrideResponse": { "type": "object", "properties": { "message": { "type": "string" }, "pricing_override": { "$ref": "#/components/schemas/PricingOverride" } } }, "ListPricingOverridesResponse": { "type": "object", "description": "When `limit`, `offset`, or `search` is supplied, `count` reflects the returned page while `total_count` reflects the full matching set. Otherwise (backward-compatible, non-paginated path) `total_count` equals `count` and `limit`/`offset` describe the full unpaged result.\n", "properties": { "pricing_overrides": { "type": "array", "items": { "$ref": "#/components/schemas/PricingOverride" } }, "count": { "type": "integer", "description": "Number of overrides in this response" }, "total_count": { "type": "integer", "description": "Total number of overrides matching the filters" }, "limit": { "type": "integer", "description": "Page size used for this response" }, "offset": { "type": "integer", "description": "Offset used for this response" } } }, "SkillSourceType": { "type": "string", "description": "Source backing for an attached skill file.", "enum": [ "url", "dataurl", "text", "upload" ] }, "SkillFileEntry": { "type": "object", "description": "File entry used when creating or updating a skill version.", "required": [ "path", "source_type", "mime_type" ], "properties": { "path": { "type": "string", "description": "Relative file path inside the skill package.", "example": "references/style-guide.md" }, "source_type": { "$ref": "#/components/schemas/SkillSourceType" }, "content": { "type": "string", "description": "Inline file content for `text` source files." }, "source_url": { "type": "string", "format": "uri", "description": "HTTP or HTTPS URL for `url` source files." }, "dataurl": { "type": "string", "description": "Data URL payload for `dataurl` source files.", "example": "data:text/plain;base64,SGVsbG8=" }, "upload_id": { "type": "string", "description": "Upload identifier returned by the multipart upload endpoint." }, "storage_key": { "type": "string", "description": "Object-storage key for an uploaded or stored file." }, "blob_id": { "type": "string", "description": "Database blob ID used when object storage is not configured." }, "mime_type": { "type": "string", "description": "MIME type for the file.", "example": "text/markdown" } } }, "SkillFile": { "allOf": [ { "$ref": "#/components/schemas/SkillFileEntry" }, { "type": "object", "description": "Persisted file attached to a skill version.", "properties": { "id": { "type": "string", "description": "File row ID." }, "skill_version_id": { "type": "string", "description": "Version snapshot ID this file belongs to." }, "file_size_bytes": { "type": "integer", "format": "int64", "description": "File size in bytes when known." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "SkillVersion": { "type": "object", "description": "Immutable skill version snapshot.", "properties": { "id": { "type": "string" }, "skill_id": { "type": "string" }, "version": { "type": "string", "example": "1.0.0" }, "skill_md_body": { "type": "string", "description": "SKILL.md body for this version. Included when a full version is loaded." }, "frontmatter_snapshot": { "type": "object", "additionalProperties": true, "description": "Frontmatter snapshot for this version." }, "created_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/SkillFile" } } } }, "Skill": { "type": "object", "description": "Skill repository entry and currently served version metadata.", "properties": { "id": { "type": "string" }, "name": { "type": "string", "example": "review-migrations" }, "description": { "type": "string", "example": "Reviews database migration safety and rollback behavior." }, "license": { "type": "string", "nullable": true, "example": "MIT" }, "compatibility": { "type": "string", "nullable": true, "example": "Claude Code, Codex" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Metadata emitted under the `metadata` frontmatter key." }, "extra_frontmatter": { "type": "object", "additionalProperties": true, "description": "Additional top-level SKILL.md frontmatter fields." }, "allowed_tools": { "type": "string", "nullable": true, "description": "Tool guidance emitted in SKILL.md frontmatter." }, "skill_md_body": { "type": "string", "description": "Markdown body of the composed SKILL.md." }, "latest_version": { "type": "string", "description": "Currently served version.", "example": "1.0.0" }, "created_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "files": { "type": "array", "description": "Files attached to the currently served version.", "items": { "$ref": "#/components/schemas/SkillFile" } }, "file_count": { "type": "integer", "format": "int64", "description": "Number of files in the currently served version." }, "highest_version": { "type": "string", "description": "Highest created SemVer for validation, even if an older version is served.", "example": "1.2.0" } } }, "CreateSkillRequest": { "type": "object", "required": [ "name", "description", "skill_md_body", "version" ], "properties": { "name": { "type": "string", "description": "Immutable skill name. Lowercase letters, numbers, and single hyphens only.", "example": "review-migrations" }, "description": { "type": "string", "maxLength": 1024 }, "license": { "type": "string", "nullable": true }, "compatibility": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "extra_frontmatter": { "type": "object", "additionalProperties": true }, "allowed_tools": { "type": "string", "nullable": true }, "skill_md_body": { "type": "string" }, "version": { "type": "string", "example": "1.0.0" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/SkillFileEntry" } } } }, "UpdateSkillRequest": { "type": "object", "required": [ "description", "skill_md_body", "version" ], "properties": { "description": { "type": "string", "maxLength": 1024 }, "license": { "type": "string", "nullable": true }, "compatibility": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "extra_frontmatter": { "type": "object", "additionalProperties": true }, "allowed_tools": { "type": "string", "nullable": true }, "skill_md_body": { "type": "string" }, "version": { "type": "string", "example": "1.0.1" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/SkillFileEntry" } }, "serve": { "type": "boolean", "description": "When false, creates a new version without making it the served version.", "default": true } } }, "SkillResponse": { "type": "object", "properties": { "skill": { "$ref": "#/components/schemas/Skill" } } }, "ListSkillsResponse": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "total": { "type": "integer", "format": "int64" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "ListSkillVersionsResponse": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/SkillVersion" } }, "total": { "type": "integer", "format": "int64" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "UploadSkillFileRequest": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload. Exactly one file part is accepted." }, "path": { "type": "string", "description": "Optional relative path to store with the uploaded file.", "example": "references/style-guide.md" } } }, "UploadSkillFileResponse": { "type": "object", "properties": { "upload_id": { "type": "string" }, "storage_key": { "type": "string", "description": "Object-storage key when object storage is configured." }, "blob_id": { "type": "string", "description": "DB blob ID when object storage is not configured." }, "path": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "file_size_bytes": { "type": "integer", "format": "int64" } } }, "SkillOrphanCleanupResponse": { "type": "object", "properties": { "deleted_db_blobs": { "type": "integer", "format": "int64" }, "deleted_storage_objects": { "type": "integer" }, "object_storage_configured": { "type": "boolean" }, "message": { "type": "string" } } }, "AllSkillsVersionResponse": { "type": "object", "properties": { "version": { "type": "string", "example": "1.2.0" } } }, "BumpAllSkillsVersionRequest": { "type": "object", "required": [ "bump" ], "properties": { "bump": { "type": "string", "enum": [ "patch", "minor", "major" ] } } }, "ShiftSkillVersionRequest": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "string", "example": "1.0.0" } } }, "ClaudeCodeSkillMarketplace": { "type": "object", "description": "Claude Code marketplace document generated by Bifrost.", "properties": { "name": { "type": "string" }, "owner": { "type": "string" }, "plugins": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "CodexSkillMarketplace": { "type": "object", "description": "Codex marketplace document generated by Bifrost.", "properties": { "name": { "type": "string" }, "interface": { "type": "object", "additionalProperties": true }, "plugins": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "LogEntry": { "type": "object", "description": "Log entry", "properties": { "id": { "type": "string" }, "parent_request_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "success", "error" ] }, "object": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "number_of_retries": { "type": "integer" }, "fallback_index": { "type": "integer" }, "latency": { "type": "number" }, "cost": { "type": "number" }, "selected_key_id": { "type": "string" }, "selected_key_name": { "type": "string" }, "virtual_key_id": { "type": "string" }, "virtual_key_name": { "type": "string", "nullable": true }, "routing_engines_used": { "type": "array", "items": { "type": "string" }, "description": "Array of routing engines used for this request (routing-rule, governance, or loadbalancing)", "nullable": true }, "routing_rule_id": { "type": "string", "nullable": true }, "routing_rule_name": { "type": "string", "nullable": true }, "stream": { "type": "boolean" }, "raw_request": { "type": "string" }, "raw_response": { "type": "string" }, "redaction_mapping": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": { "type": "string" } }, "output": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Phase-scoped placeholder-to-original-value mappings for reversible redactions. Present only on log detail responses when the caller has `Logs:Reveal`." }, "created_at": { "type": "string", "format": "date-time" }, "token_usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "error_details": { "$ref": "#/components/schemas/BifrostError" }, "input_history": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "responses_input_history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } }, "output_message": { "$ref": "#/components/schemas/ChatMessage" }, "responses_output": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "file_search_call", "computer_call", "computer_call_output", "web_search_call", "web_fetch_call", "function_call", "function_call_output", "code_interpreter_call", "local_shell_call", "local_shell_call_output", "mcp_call", "custom_tool_call", "custom_tool_call_output", "image_generation_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_responses", "reasoning", "item_reference", "refusal" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "role": { "type": "string", "enum": [ "assistant", "user", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } } ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "description": "Tool call output. A plain string for function/custom/local-shell tool\noutputs, an array of content blocks for structured function tool\noutputs, or a computer-tool screenshot object for computer_call_output.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "input_image", "input_file", "input_audio", "output_text", "refusal", "reasoning_text" ] }, "file_id": { "type": "string" }, "text": { "type": "string" }, "signature": { "type": "string" }, "image_url": { "type": "string" }, "detail": { "type": "string" }, "file_data": { "type": "string" }, "file_url": { "type": "string" }, "filename": { "type": "string" }, "file_type": { "type": "string" }, "input_audio": { "type": "object", "required": [ "format", "data" ], "properties": { "format": { "type": "string", "enum": [ "mp3", "wav" ] }, "data": { "type": "string" } } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_citation", "url_citation", "container_file_citation", "file_path" ] }, "index": { "type": "integer" }, "file_id": { "type": "string" }, "text": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "filename": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "container_id": { "type": "string" } } } }, "logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "array", "items": { "type": "integer" } }, "logprob": { "type": "number" }, "token": { "type": "string" } } } } } } }, "refusal": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, { "type": "object", "description": "Computer tool call output (computer_screenshot).", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ] }, "file_id": { "type": "string" }, "image_url": { "type": "string" } } } ] }, "action": { "type": "object" }, "error": { "type": "string" }, "queries": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "string" } } } }, "embedding_output": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, "params": { "type": "object", "additionalProperties": true }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function", "custom" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true }, "enum": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } } }, "strict": { "type": "boolean" } } }, "custom": { "type": "object", "properties": { "format": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "grammar": { "type": "object", "required": [ "definition", "syntax" ], "properties": { "definition": { "type": "string" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ] } } } } } } }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "function" ], "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "id": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } }, "speech_input": { "type": "object", "additionalProperties": true }, "transcription_input": { "type": "object", "additionalProperties": true }, "image_generation_input": { "type": "object", "additionalProperties": true }, "speech_output": { "type": "object", "additionalProperties": true }, "transcription_output": { "type": "object", "additionalProperties": true }, "image_generation_output": { "type": "object", "additionalProperties": true }, "cache_debug": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata captured from request headers (configured via logging_headers or x-bf-lh-* prefix)" }, "selected_key": { "type": "object", "additionalProperties": true }, "virtual_key": { "type": "object", "additionalProperties": true }, "passthrough_request_body": { "type": "string", "description": "Raw passthrough request body (for passthrough integration routes)" }, "passthrough_response_body": { "type": "string", "description": "Raw passthrough response body (for passthrough integration routes)" }, "routing_engine_logs": { "type": "object", "additionalProperties": true, "description": "Detailed logs from the routing engine decision process" }, "is_large_payload_request": { "type": "boolean", "description": "Whether the request payload exceeded the large payload threshold" }, "is_large_payload_response": { "type": "boolean", "description": "Whether the response payload exceeded the large payload threshold" }, "rerank_output": { "type": "object", "additionalProperties": true, "description": "Rerank operation output" }, "video_generation_input": { "type": "object", "additionalProperties": true, "description": "Video generation request input" }, "video_generation_output": { "type": "object", "additionalProperties": true, "description": "Video generation response output" }, "video_retrieve_output": { "type": "object", "additionalProperties": true, "description": "Video retrieve response output" }, "video_list_output": { "type": "object", "additionalProperties": true, "description": "Video list response output" }, "video_delete_output": { "type": "object", "additionalProperties": true, "description": "Video delete response output" }, "video_download_output": { "type": "object", "additionalProperties": true, "description": "Video download response output" }, "list_models_output": { "type": "object", "additionalProperties": true, "description": "List models response output" } } }, "SearchLogsResponse": { "type": "object", "description": "Search logs response", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } }, "pagination": { "type": "object", "description": "Pagination metadata for list responses", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sort_by": { "type": "string", "enum": [ "timestamp", "latency", "tokens", "cost" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of items matching the query" } } }, "stats": { "$ref": "#/components/schemas/LogStats" }, "has_logs": { "type": "boolean", "description": "Whether any logs exist in the system" } } }, "LogStats": { "type": "object", "description": "Log statistics", "required": [ "total_requests", "total_tokens", "total_cost", "average_latency", "success_rate", "user_facing_success_rate", "user_facing_total_requests" ], "properties": { "total_requests": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" }, "total_cost": { "type": "number" }, "average_latency": { "type": "number" }, "success_rate": { "type": "number", "description": "Percentage of completed provider attempts that succeeded" }, "user_facing_success_rate": { "type": "number", "description": "Percentage of user requests that ultimately succeeded, counting fallback chains as one request" }, "user_facing_total_requests": { "type": "integer", "format": "int64", "description": "Count of root requests used as the denominator for user_facing_success_rate" }, "cache_hit_rate_total_requests": { "type": "integer", "format": "int64", "description": "Completed requests used as the local-cache hit-rate denominator" }, "direct_cache_hits": { "type": "integer", "format": "int64", "description": "Number of direct local-cache hits" }, "semantic_cache_hits": { "type": "integer", "format": "int64", "description": "Number of semantic local-cache hits" } } }, "DeleteLogsRequest": { "type": "object", "description": "Delete logs request", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" } } } }, "RecalculateCostRequest": { "type": "object", "description": "Recalculate cost request", "properties": { "filters": { "type": "object", "description": "Log search filters", "properties": { "providers": { "type": "array", "items": { "type": "string" } }, "models": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "objects": { "type": "array", "items": { "type": "string" } }, "selected_key_ids": { "type": "array", "items": { "type": "string" } }, "virtual_key_ids": { "type": "array", "items": { "type": "string" } }, "routing_rule_ids": { "type": "array", "items": { "type": "string" } }, "routing_engine_used": { "type": "array", "items": { "type": "string" }, "description": "Filter by routing engine (routing-rule, governance, or loadbalancing)" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "min_latency": { "type": "number" }, "max_latency": { "type": "number" }, "min_tokens": { "type": "integer" }, "max_tokens": { "type": "integer" }, "min_cost": { "type": "number" }, "max_cost": { "type": "number" }, "missing_cost_only": { "type": "boolean" }, "content_search": { "type": "string" } } }, "limit": { "type": "integer", "description": "Maximum number of logs to process (default 200, max 1000)" } } }, "RecalculateCostResponse": { "type": "object", "description": "Recalculate cost job status", "properties": { "id": { "type": "string", "description": "Background job ID" }, "status": { "type": "string", "description": "Current job status" }, "total": { "type": "integer", "format": "int64", "description": "Total matching logs queued for recalculation" }, "processed": { "type": "integer", "format": "int64", "description": "Logs processed so far" }, "updated": { "type": "integer", "format": "int64", "description": "Logs updated with new costs" }, "skipped": { "type": "integer", "format": "int64", "description": "Logs skipped during processing" }, "message": { "type": "string", "description": "Optional progress message" }, "last_error": { "type": "string", "description": "Last error encountered by the job" }, "started_at": { "type": "string", "format": "date-time", "description": "Job start time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last status update time" } } }, "ClearCacheResponse": { "type": "object", "description": "Clear cache response", "properties": { "message": { "type": "string", "example": "Cache cleared successfully" } } }, "AuditEventType": { "type": "string", "description": "Classifies the audit event.", "enum": [ "activity", "monitor", "control" ] }, "AuditAction": { "type": "string", "description": "The CADF action performed.", "enum": [ "create", "read", "update", "delete", "authenticate", "authorize", "access", "enable", "disable", "start", "stop", "backup", "restore", "export", "import" ] }, "AuditOutcome": { "type": "string", "description": "The CADF outcome of the action.", "enum": [ "success", "failure", "pending" ] }, "AuditResourceType": { "type": "string", "description": "The type of resource involved in an audit event (initiator or target).", "enum": [ "user", "api_key", "system", "provider", "virtual_key", "team", "customer", "role", "permission", "guardrail", "mcp_client", "mcp_tool_group", "plugin", "config", "session", "inference" ] }, "AuditResource": { "type": "object", "description": "A CADF resource (initiator, target, or observer).", "properties": { "id": { "type": "string", "description": "Unique identifier of the resource." }, "typeURI": { "type": "string", "description": "Resource type URI (e.g., \"bifrost/user\", \"bifrost/api_key\")." }, "name": { "type": "string", "description": "Human-readable name of the resource." }, "host": { "type": "string", "description": "Hostname or IP address associated with the resource." } }, "required": [ "id", "typeURI" ] }, "AuditReason": { "type": "object", "description": "The CADF reason for an outcome (especially for failures).", "properties": { "reasonCode": { "type": "string", "description": "Machine-readable code (e.g., \"401\", \"FORBIDDEN\")." }, "reasonType": { "type": "string", "description": "Category of reason (e.g., \"HTTP\", \"policy\")." }, "message": { "type": "string", "description": "Human-readable description." } } }, "AuditAttachment": { "type": "object", "description": "Additional CADF data attached to an event.", "properties": { "name": { "type": "string", "description": "Identifies the attachment." }, "contentType": { "type": "string", "description": "MIME type of the content." }, "content": { "type": "string", "description": "Attachment data (typically a JSON string)." } }, "required": [ "name", "contentType", "content" ] }, "AuditEvent": { "type": "object", "description": "A CADF-compliant audit event.", "properties": { "id": { "type": "string", "description": "Unique identifier for this event (UUID)." }, "typeURI": { "type": "string", "description": "Event type URI (e.g., \"http://schemas.bifrost.io/audit/api/v1\")." }, "eventType": { "$ref": "#/components/schemas/AuditEventType" }, "eventTime": { "type": "string", "format": "date-time", "description": "When the event occurred (RFC 3339)." }, "action": { "$ref": "#/components/schemas/AuditAction" }, "outcome": { "$ref": "#/components/schemas/AuditOutcome" }, "initiator": { "$ref": "#/components/schemas/AuditResource" }, "target": { "$ref": "#/components/schemas/AuditResource" }, "observer": { "$ref": "#/components/schemas/AuditResource" }, "reason": { "$ref": "#/components/schemas/AuditReason" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AuditAttachment" } }, "tags": { "type": "array", "description": "Searchable labels for categorization.", "items": { "type": "string" } }, "requestMethod": { "type": "string", "description": "HTTP method (GET, POST, etc.)." }, "requestPath": { "type": "string", "description": "HTTP request path." }, "requestIP": { "type": "string", "description": "Client IP address." }, "userAgent": { "type": "string", "description": "HTTP User-Agent header." }, "duration": { "type": "integer", "format": "int64", "description": "Request duration in milliseconds." }, "signature": { "type": "string", "description": "HMAC-SHA256 signature for tamper detection." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the record was created in the database." } }, "required": [ "id", "typeURI", "eventType", "eventTime", "action", "outcome", "initiator", "target", "observer", "signature", "createdAt" ] }, "AuditLogsResult": { "type": "object", "description": "A paginated result of audit logs.", "properties": { "audit_logs": { "type": "array", "description": "The list of audit events.", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "total": { "type": "integer", "format": "int64", "description": "Total count of events matching the filter." }, "page": { "type": "integer", "description": "Current page number." }, "limit": { "type": "integer", "description": "Page size." }, "total_pages": { "type": "integer", "description": "Total number of pages." }, "has_more": { "type": "boolean", "description": "Whether there are more results." }, "next_cursor": { "type": "string", "description": "Opaque cursor for the next page (cursor-based pagination)." } }, "required": [ "audit_logs", "total", "page", "limit", "total_pages", "has_more" ] }, "AuditLogResponse": { "type": "object", "description": "Response wrapper for a single audit log entry.", "properties": { "audit_log": { "$ref": "#/components/schemas/AuditEvent" } }, "required": [ "audit_log" ] }, "AuditFilterKeyPair": { "type": "object", "description": "An id/name pair used for initiator and target filter dropdowns.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "AuditFilterDataResponse": { "type": "object", "description": "Distinct values available for each audit log filter dimension.", "properties": { "actions": { "type": "array", "items": { "type": "string" } }, "outcomes": { "type": "array", "items": { "type": "string" } }, "event_types": { "type": "array", "items": { "type": "string" } }, "initiator_types": { "type": "array", "items": { "type": "string" } }, "target_types": { "type": "array", "items": { "type": "string" } }, "request_methods": { "type": "array", "items": { "type": "string" } }, "initiators": { "type": "array", "items": { "$ref": "#/components/schemas/AuditFilterKeyPair" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/AuditFilterKeyPair" } }, "request_paths": { "type": "array", "items": { "type": "string" } }, "request_ips": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "AuditVerifyResult": { "type": "object", "description": "The result of an audit log signature verification.", "properties": { "valid": { "type": "boolean", "description": "Whether the stored signature matches the recomputed signature." }, "computed": { "type": "string", "description": "The signature recomputed from the stored event fields." }, "stored": { "type": "string", "description": "The signature persisted with the event." } }, "required": [ "valid", "computed", "stored" ] }, "WebhookEvent": { "type": "string", "enum": [ "async_job.completed", "async_job.failed" ], "description": "A terminal async-job event a webhook endpoint can subscribe to:\n- async_job.completed: an async job finished successfully\n- async_job.failed: an async job finished with an error\n" }, "WebhookEndpointRequest": { "type": "object", "required": [ "name", "url", "events" ], "description": "Create or update body for a webhook endpoint. The signing secret is never\naccepted here — it is generated by the server and returned once at creation,\nand can only be changed through the rotate-secret endpoint.\n", "properties": { "name": { "type": "string", "description": "Unique endpoint name." }, "url": { "type": "string", "description": "Delivery URL. HTTPS is required unless allow_private_network is set." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "Events this endpoint subscribes to." }, "headers": { "type": "object", "additionalProperties": { "description": "A secret-bearing value. May be a plain string, or an object referencing an\nenvironment variable so the literal value is never stored inline.\n", "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "value": { "type": "string" }, "env_var": { "type": "string" }, "from_env": { "type": "boolean" } }, "additionalProperties": false } ] }, "description": "Custom headers sent with every delivery. Values support env var syntax\n(\"env.MY_VAR\") and are encrypted at rest. Reserved delivery headers\n(webhook-id, webhook-timestamp, webhook-signature, content-type, etc.)\ncannot be overridden.\n" }, "include_response": { "type": "boolean", "default": false, "description": "Inline the job response into delivery payloads, capped by max_response_payload_kbs." }, "allow_private_network": { "type": "boolean", "default": false, "description": "Permit private-network receivers and plain http. Link-local and metadata addresses stay blocked." }, "disabled": { "type": "boolean", "default": false, "description": "Register the endpoint without delivering to it." }, "max_retries": { "type": "integer", "minimum": 0, "description": "Retries after the first failed attempt (default 4). 0 selects the default." }, "retry_backoff_initial_seconds": { "type": "integer", "minimum": 0, "description": "Delay before the first retry; each further retry doubles it (default 30). 0 selects the default." }, "retry_backoff_max_seconds": { "type": "integer", "minimum": 0, "description": "Cap on the per-retry delay (default 1800). 0 selects the default." }, "attempt_timeout_seconds": { "type": "integer", "minimum": 0, "description": "End-to-end bound for one delivery attempt (default 10). 0 selects the default." }, "max_response_payload_kbs": { "type": "integer", "minimum": 0, "description": "Cap for inlined response payloads in KB when include_response is set (default 256). 0 selects the default." }, "max_concurrent_deliveries": { "type": "integer", "minimum": 0, "description": "Concurrent in-flight deliveries to this endpoint per node (default 10). 0 selects the default." } } }, "WebhookEndpoint": { "type": "object", "description": "A registered webhook endpoint. The signing secret is never included in this\nrepresentation; custom header values are redacted.\n", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "headers": { "type": "object", "additionalProperties": { "type": "object", "description": "A redacted secret-bearing value as returned in responses. The literal is\nmasked (\"\"); ref and type describe the original source when set.\n", "properties": { "value": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": false }, "description": "Custom delivery header values, redacted." }, "include_response": { "type": "boolean" }, "allow_private_network": { "type": "boolean" }, "disabled": { "type": "boolean" }, "max_retries": { "type": "integer" }, "retry_backoff_initial_seconds": { "type": "integer" }, "retry_backoff_max_seconds": { "type": "integer" }, "attempt_timeout_seconds": { "type": "integer" }, "max_response_payload_kbs": { "type": "integer" }, "max_concurrent_deliveries": { "type": "integer" }, "consecutive_failures": { "type": "integer", "description": "Number of consecutive failed deliveries; reset on the next success." }, "last_success_at": { "type": "string", "format": "date-time" }, "last_failure_at": { "type": "string", "format": "date-time" }, "config_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookEndpointList": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "count": { "type": "integer", "description": "Number of endpoints in this page." }, "total_count": { "type": "integer", "description": "Total endpoints matching the filters." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "WebhookEndpointWithSecret": { "type": "object", "description": "Returned once when an endpoint is created or its secret is rotated. The\nsecret is shown a single time and cannot be retrieved again.\n", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "description": "The signing secret in whsec_ format. Store it now; it is never returned again." } } }, "TestWebhookRequest": { "type": "object", "required": [ "event" ], "properties": { "event": { "$ref": "#/components/schemas/WebhookEvent", "description": "The event to render for the sample delivery. Must be one the endpoint subscribes to." } } }, "TestWebhookResponse": { "type": "object", "properties": { "delivered": { "type": "boolean", "description": "True when the receiver answered with a 2xx status." }, "receiver_status_code": { "type": "integer", "description": "The HTTP status the receiver returned. Present when the request reached the receiver." }, "error": { "type": "string", "description": "Failure reason when the delivery could not be completed." } } }, "WebhookDeliveryOutcome": { "type": "string", "enum": [ "delivered", "retryable_failure", "permanent_failure", "exhausted" ], "description": "Outcome of a single delivery attempt:\n- delivered: the receiver returned 2xx\n- retryable_failure: failed but will be retried\n- permanent_failure: failed in a way that is not retried\n- exhausted: retries were used up without success\n" }, "WebhookDelivery": { "type": "object", "description": "One delivery attempt in an endpoint's history.", "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string", "description": "The webhook-id header value; stable across retries of the same event." }, "endpoint_id": { "type": "string" }, "async_job_id": { "type": "string" }, "request_id": { "type": "string", "description": "The async job's inference request id — the same id the LLM logs record. Empty when the job row expired before the attempt." }, "event": { "$ref": "#/components/schemas/WebhookEvent" }, "attempt_no": { "type": "integer" }, "outcome": { "$ref": "#/components/schemas/WebhookDeliveryOutcome" }, "status_code": { "type": "integer", "description": "HTTP status the receiver returned, when the attempt reached it." }, "error": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "WebhookDeliveryList": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "RedeliverWebhookResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "queued" }, "webhook_id": { "type": "string", "description": "The original delivery's webhook-id, reused so receivers can deduplicate the replay." } } }, "WebhookStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } }, "NotificationSeverity": { "type": "string", "description": "Visual weight the dashboard gives the notification.", "enum": [ "info", "success", "warning", "error" ] }, "NotificationAudience": { "type": "string", "description": "Who the notification reaches. `all` is every dashboard user; `roles` limits\nit to the listed RBAC roles, enforced on both the list endpoint and the\nWebSocket fan-out.\n", "enum": [ "all", "roles" ] }, "NotificationInput": { "type": "object", "description": "A notification to publish. IDs and both timestamps are assigned by the\nserver and cannot be supplied.\n", "required": [ "audience", "severity", "title", "message" ], "properties": { "audience": { "$ref": "#/components/schemas/NotificationAudience" }, "role_ids": { "type": "array", "description": "Required when `audience` is `roles`, and must be empty otherwise.\nDuplicates are removed and the list is sorted before it is stored.\n", "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "severity": { "$ref": "#/components/schemas/NotificationSeverity" }, "title": { "type": "string", "description": "Trimmed before validation.", "minLength": 1, "maxLength": 160 }, "message": { "type": "string", "description": "Trimmed before validation.", "minLength": 1, "maxLength": 4000 }, "action_label": { "type": "string", "description": "Label for the notification's action. Must be supplied together with\n`action_path`, or not at all.\n" }, "action_path": { "type": "string", "description": "Dashboard-internal absolute path the action opens, for example\n`/workspace/providers`. Absolute URLs, host-relative `//` paths, and\nanything not starting with `/` are rejected, so a notification cannot\nbe used to send users off-site.\n", "pattern": "^/(?!/).*" } } }, "Notification": { "type": "object", "description": "A persisted dashboard notification.", "required": [ "id", "audience", "severity", "title", "message", "created_at", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "audience": { "$ref": "#/components/schemas/NotificationAudience" }, "role_ids": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "severity": { "$ref": "#/components/schemas/NotificationSeverity" }, "title": { "type": "string" }, "message": { "type": "string" }, "action_label": { "type": "string" }, "action_path": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Always 30 days after `created_at`. Expired rows are pruned hourly and\nare not returned once pruned.\n" } } }, "NotificationList": { "type": "object", "description": "A page of notifications, newest first, already filtered to what the caller's\nrole may see.\n", "required": [ "notifications" ], "properties": { "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "next_cursor": { "type": "string", "description": "Opaque cursor for the next page. Absent when there are no further\nresults. Pass it back as the `cursor` query parameter.\n" } } } } } }