{ "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": "Decisions", "description": "Structured decisions evaluated against annotated function-tool definitions" }, { "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": "Typesafe Integration", "description": "Typesafe compatible API endpoints (/typesafe/*)" }, { "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" }, { "name": "API Keys", "description": "Management API key issuance, scoping, and revocation" } ], "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": [] }, { "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/decisions": { "post": { "operationId": "createDecision", "summary": "Evaluate a decision", "description": "Evaluates state against a map of named questions and returns one typed\nanswer per question, with per-answer confidence, probabilities, and\nlegend metadata. Served by decision providers such as Typesafe's jev models.\n", "tags": [ "Decisions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionResponse" } } } }, "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/typesafe/v1/systemone": { "post": { "operationId": "typesafeSystemOne", "summary": "Evaluate state (Typesafe format)", "description": "Evaluates state against a map of named questions using Typesafe's native\nSystem One API. The request body matches Typesafe's native format; question\nidentifiers become result field names.\n", "tags": [ "Typesafe Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state", "model", "questions" ], "properties": { "state": { "description": "A plain string, or structured data (object or array) to evaluate.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "model": { "type": "string", "description": "Typesafe model identifier (e.g. `jev-1.13.0`, `jev-latest`)." }, "questions": { "type": "object", "minProperties": 1, "description": "Map of named questions.", "additionalProperties": { "type": "object", "required": [ "type", "instructions" ], "properties": { "type": { "type": "string", "enum": [ "noul", "choice", "score" ], "description": "Question type. `noul` returns a probability from 0 to 1, `choice` a selection with probabilities, `score` a probability-weighted rubric value." }, "instructions": { "description": "Question instructions. A string, or structured data.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "criteria": { "description": "Optional `true`/`false` descriptions for `noul`; a map of option\nto description for `choice` (at most 255 options); an ordered\narray of 2-10 level descriptions for `score`.\n", "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "array", "items": { "type": "string" } } ] } } } } } } } } }, "responses": { "200": { "description": "Successful response in Typesafe's native shape", "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "answers" ], "properties": { "model": { "type": "string", "description": "Model version that performed the evaluation" }, "answers": { "type": "object", "description": "Map matching question identifiers to answers", "additionalProperties": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "noul", "choice", "score" ] }, "noul": { "type": "number", "description": "Probability from 0 to 1 (noul answers)" }, "choice": { "type": "string", "description": "Selected option (choice answers)" }, "score": { "type": "number", "description": "Probability-weighted value (score answers)" }, "probabilities": { "type": "object", "additionalProperties": { "type": "number" } }, "legend": { "type": "object", "additionalProperties": { "type": "string" } }, "confidence": { "type": "number" } } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } } } } } } }, "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": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/typesafe/v1/models": { "get": { "operationId": "typesafeListModels", "summary": "List models (Typesafe format)", "description": "Lists available Typesafe models in the native shape. Typesafe documents no\nupstream listing endpoint, so the catalog is served from Bifrost's model\ndatasheet.\n", "tags": [ "Typesafe Integration" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "jev-latest" }, "description": { "type": "string" }, "release_date": { "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" } } } } }, "security": [ { "BearerAuth": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "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": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/health": { "get": { "operationId": "getHealth", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Health check", "description": "Returns the health status of the Bifrost server. Checks connectivity to config store,\nlog store, and vector store if configured.\nUnauthenticated by design - `/health` is in the auth middleware's system whitelist.\n", "tags": [ "Health" ], "security": [], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get version", "description": "Returns the current Bifrost version information.\nUnauthenticated by design - `/api/version` is in the auth middleware's system whitelist.\n", "tags": [ "Configuration" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } } }, "/api/proxy-config": { "get": { "operationId": "getProxyConfig", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get proxy configuration", "description": "Retrieves the current global proxy configuration.\n", "tags": [ "Configuration" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "description": "Proxy URL (http or https). Private and loopback hosts are accepted; link-local and unspecified addresses are rejected." }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update proxy configuration", "description": "Updates the global proxy configuration.\nSetting a new proxy url or turning on skip_tls_verify requires a genuinely\nauthenticated admin session - it is refused with 403 if dashboard authentication is\ndisabled or unconfigured, even though other management endpoints remain reachable in\nthat state. Saving other fields with the stored url, disabling the proxy, or turning\nskip_tls_verify off is allowed.\nThe url follows the same destination rule as a provider base_url: it must be an http\nor https URL whose host resolves to a routable address. Private and loopback hosts are\naccepted (a self-hosted egress proxy is the normal setup); link-local (for example the\ncloud metadata endpoint) and unspecified addresses are refused with 400.\n", "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", "description": "Proxy URL (http or https). Private and loopback hosts are accepted; link-local and unspecified addresses are rejected." }, "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": [] }, { "BasicAuth": [] } ], "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" } } } }, "403": { "description": "A new proxy url was supplied or skip_tls_verify was turned on, and dashboard authentication is disabled or unconfigured (the request was not genuinely authenticated)" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/pricing/force-sync": { "post": { "operationId": "forceSyncPricing", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Force pricing sync", "description": "Triggers an immediate pricing sync and resets the pricing sync timer.\n", "tags": [ "Configuration" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List users", "description": "Returns a paginated list of users with optional search.\n", "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": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create user", "description": "Manually creates a new user in the organization.\n", "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": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get user", "description": "Returns a single Enterprise user.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MessageResponse" }, { "type": "object", "properties": { "redivision_job_ids": { "type": "array", "items": { "type": "string" }, "description": "One queued job per equal-split governance project the user belonged to, since removing them enlarges every remaining member's slice of every cap. Present only when such projects were affected. Progress is reported on the `redivision_progress` WebSocket channel under each id." } } } ] } } } }, "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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/me/vk-creation-policy": { "get": { "operationId": "getMyVirtualKeyCreationPolicy", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get the calling user's virtual-key creation policy", "description": "Resolves the access profile that would govern a virtual key the **calling** user creates,\nreturning its name or none. Whether governance applies at all is decided separately from the\n`VirtualKeys:CreateStandalone` permission (see `/api/governance/users/me/permissions`); this\nendpoint only resolves the profile, and the create form combines the two.\n\nSelf-scoped: it always describes the caller and takes no user ID. Returns\n`{\"has_access_profile\": false}` when the caller has no per-user identity (local admin) or holds\nno active access profile. When several of their profiles qualify, the highest-ranked one governs.\nHolding no profile does not by itself block a caller from creating a key: given\n`VirtualKeys:Create`, the key is created ungoverned.\n", "tags": [ "Users", "Virtual Keys" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Virtual-key creation policy for the calling user", "content": { "application/json": { "schema": { "type": "object", "required": [ "has_access_profile" ], "properties": { "has_access_profile": { "type": "boolean", "description": "Whether the caller holds an access profile that would govern keys they create." }, "profile_name": { "type": "string", "description": "Name of the governing access profile. Present only when `has_access_profile` is true." } } } } } }, "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `UserProvisioning:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get user's teams", "description": "Returns the list of teams a user belongs to, including the membership source.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete user governance", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List virtual keys available to a user", "description": "Returns every virtual key assigned to the user, independent of access profiles, so\ndirectly-assigned standalone keys are visible alongside profile-issued ones.\n", "tags": [ "Users", "Virtual Keys" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "User virtual keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "virtual_keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "is_access_profile_managed": { "type": "boolean", "description": "True when an access profile governs this key, in which case its policy is edit-locked and changed by editing and propagating the profile.\n" } } } } } } } } } } }, "post": { "operationId": "addUserVirtualKey", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Mint an extra virtual key for a user", "description": "Issues an additional virtual key for the user.\n\nVirtual keys are scoped to the **user**, not to any one access profile: what a request may\ndo with the key is read from whichever of the user's active profiles grants it, and each of\nthose profiles is a separate routing candidate the request may be served by. The user must\ntherefore hold at least one access profile — the request returns 404 otherwise — but the key\nis not tied to the profile that happened to be current when it was minted, and it survives\nthat profile being detached as long as the user still holds another.\n", "tags": [ "Users", "Virtual Keys" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "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 has no access profiles" }, "409": { "description": "A virtual key with this name already exists" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get user by email", "description": "Returns a single Enterprise user resolved by URL-encoded email address.\n", "tags": [ "Users" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List team members", "description": "Returns all members of a team with their user details and membership source.\n", "tags": [ "Teams" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Add team member", "description": "Adds a user to a team. Both the team and user must exist.\n", "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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Remove team member", "description": "Removes a user from a team.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Logout", "description": "Logs out the current user and invalidates the session token.\n", "tags": [ "Session" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] }, { "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Check if authentication is enabled", "description": "Returns whether authentication is enabled and if the current token is valid.\n", "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] }, { "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List all providers", "description": "Returns a list of all configured providers with their configurations and status.\n", "tags": [ "Providers" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Add a new provider", "description": "Adds a new provider with the specified configuration.\nSetting network_config.base_url or network_config.allow_private_network requires a\ngenuinely authenticated admin session - it is refused with 403 if dashboard\nauthentication is disabled or unconfigured, even though other management endpoints\nremain reachable in that state. allow_private_network is guarded even without a base\nURL, because it also governs which addresses key-level URLs (Ollama/SGL/VLLM) may reach.\nThe same applies to settings that let a third party read credentials in flight:\nproxy_config.url, proxy_config.ca_cert_pem, network_config.ca_cert_pem,\nnetwork_config.insecure_skip_verify, and any absolute (scheme and host)\ncustom_provider_config.request_path_overrides value.\n", "tags": [ "Providers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProviderRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" } } } }, "403": { "description": "network_config.base_url, allow_private_network, a proxy URL, a CA certificate, insecure_skip_verify, or an absolute request path override was supplied and dashboard authentication is disabled or unconfigured (the request was not genuinely authenticated)" }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get a specific provider", "description": "Returns the configuration for a specific provider.\n", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\nChanging network_config.base_url, or turning on network_config.allow_private_network\n(with or without a base URL), requires a genuinely authenticated admin session - it is\nrefused with 403 if dashboard authentication is disabled or unconfigured, even though\nother management endpoints remain reachable in that state. The same applies to setting\nor changing proxy_config.url, proxy_config.ca_cert_pem, network_config.ca_cert_pem, or\nan absolute (scheme and host) custom_provider_config.request_path_overrides value, and\nto turning on network_config.insecure_skip_verify. Sending the stored values back\nunchanged (including redacted placeholders), clearing the base URL, proxy or an\noverride, path-only overrides, or turning allow_private_network or\ninsecure_skip_verify off is allowed.\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": [] }, { "BasicAuth": [] } ], "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" } } } }, "403": { "description": "network_config.base_url, a proxy URL, a CA certificate, or an absolute request path override was changed, or allow_private_network or insecure_skip_verify was turned on, and dashboard authentication is disabled or unconfigured (the request was not genuinely authenticated)" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteProvider", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete a provider", "description": "Removes a provider from the configuration.\n", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List keys for a provider", "description": "Returns all keys configured for a specific provider.\n", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\nSetting any field that chooses the host Bifrost sends this key's credentials to\nrequires a genuinely authenticated admin session - it is refused with 403 if dashboard\nauthentication is disabled or unconfigured, even though other management endpoints\nremain reachable in that state. ollama_key_config.url, sgl_key_config.url and\nvllm_key_config.url also follow the provider base_url destination rule: private and\nloopback hosts are accepted, link-local and unspecified addresses are refused with 400.\nKey-level and per-alias regions must be vendor region identifiers (lowercase letters,\ndigits and hyphens, e.g. us-east-1); any other value is refused with 400.\nGuarded fields: ollama_key_config.url, sgl_key_config.url, vllm_key_config.url,\nazure_key_config.endpoint, databricks_key_config.workspace_url,\ngithub_copilot_key_config.github_domain,\nbedrock_key_config.endpoints.*, bedrock_mantle_key_config.endpoints.*, and\naliases..endpoint.\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": [] }, { "BasicAuth": [] } ], "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" } } } }, "403": { "description": "A key endpoint field was set, changed, or removed and dashboard authentication is disabled or unconfigured (the request was not genuinely authenticated)" }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get a specific key for a provider", "description": "Returns a single key for the specified provider.\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" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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).\nSetting, changing, or removing any field that chooses the host Bifrost sends this\nkey's credentials to requires a genuinely authenticated admin session - it is refused\nwith 403 if dashboard authentication is disabled or unconfigured, even though other\nmanagement endpoints remain reachable in that state. Sending the stored values back\nunchanged is allowed. ollama_key_config.url, sgl_key_config.url and\nvllm_key_config.url also follow the provider base_url destination rule: private and\nloopback hosts are accepted, link-local and unspecified addresses are refused with 400.\nKey-level and per-alias regions must be vendor region identifiers (lowercase letters,\ndigits and hyphens, e.g. us-east-1); any other value is refused with 400.\nGuarded fields: ollama_key_config.url, sgl_key_config.url, vllm_key_config.url,\nazure_key_config.endpoint, databricks_key_config.workspace_url,\ngithub_copilot_key_config.github_domain,\nbedrock_key_config.endpoints.*, bedrock_mantle_key_config.endpoints.*, and\naliases..endpoint.\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": [] }, { "BasicAuth": [] } ], "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" } } } }, "403": { "description": "A key endpoint field was set, changed, or removed and dashboard authentication is disabled or unconfigured (the request was not genuinely authenticated)" }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete a key from a provider", "description": "Deletes a key from the specified provider. Returns the deleted key.\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" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List all keys", "description": "Returns a list of all configured API keys across all providers.\n", "tags": [ "Providers" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `ModelProvider:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List base models", "description": "Returns a list of base models from the model catalog.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Plugins:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Plugins:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Plugins:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Plugins:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Plugins:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Plugins:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete a plugin", "description": "Removes a plugin from the configuration and stops it if running.\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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Not RBAC-gated - authorized by the credential below |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Execute MCP tool", "description": "Executes an MCP tool and returns the result.\n", "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/mcp/clients": { "get": { "operationId": "getMCPClients", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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\nTwo cases require a genuinely authenticated admin session and are refused\nwith 403 when dashboard authentication is disabled or unconfigured, even\nthough other management endpoints stay reachable in that state:\nconnection_type \"stdio\" (which runs the supplied command as a gateway\nsubprocess), and connection_type \"http\"/\"sse\" whose connection_string\nresolves to a loopback, private-network, link-local, or CGNAT address.\nPublic http/sse targets are unaffected.\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": [] }, { "BasicAuth": [] } ], "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" } } } }, "403": { "description": "The request was not genuinely authenticated (dashboard authentication is disabled or unconfigured) and connection_type is \"stdio\", or is \"http\"/\"sse\" with a connection_string resolving to a loopback, private-network, link-local, or CGNAT address." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/mcp/client/{id}": { "put": { "operationId": "editMCPClient", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Remove MCP client", "description": "Removes an MCP client from the configuration.\n", "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP client ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "tags": [ "MCP" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session / credential / flow row ID" } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session row ID (OAuth token or header credential)" } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Flow row ID" } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPGateway:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "tags": [ "MCP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Credential row primary key" } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List virtual keys", "description": "Returns a list of all virtual keys with their configurations.\n", "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 across the virtual key name, its team name, and its customer name. Enterprise additionally matches the name and email of the user the key is assigned to.", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create virtual key", "description": "Creates a new virtual key with the specified configuration.\n", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVirtualKeyRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Not RBAC-gated - authorized by the credential below |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\nDuring an active rotation grace window (client vk_rotation_cooldown), the\nprevious key value also authenticates until previous_value_expires_at.\nAn expired virtual key is rejected with 403; an inactive one still returns\nits quota with is_active false.\n", "tags": [ "Governance" ], "security": [ { "VirtualKeyAuth": [] }, { "VirtualKeyBearerAuth": [] }, { "VirtualKeyApiKeyAuth": [] }, { "VirtualKeyGoogleAuth": [] }, { "VirtualKeyAzureAuth": [] } ], "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" } } } } } }, "403": { "description": "Virtual key has expired", "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get virtual key", "description": "Returns a specific virtual key by ID.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update virtual key", "description": "Updates an existing virtual key's configuration.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete virtual key", "description": "Deletes a virtual key.\n", "tags": [ "Governance" ], "parameters": [ { "name": "vk_id", "in": "path", "required": true, "description": "Virtual key ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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}/rotate": { "post": { "operationId": "rotateVirtualKey", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "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/virtual-keys/{vk_id}/budgets/{budget_id}/override": { "put": { "operationId": "updateVirtualKeyBudgetOverride", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "User detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/virtual-keys/rotate": { "post": { "operationId": "bulkRotateVirtualKeys", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "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/teams": { "get": { "operationId": "listTeams", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List teams", "description": "Returns a list of all teams.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create team", "description": "Creates a new team.\n", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get team", "description": "Returns a specific team by ID.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update team", "description": "Updates an existing team.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete team", "description": "Deletes a team.\n", "tags": [ "Governance" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List customers attached to a team", "tags": [ "Teams", "Customers" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Customer detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/customers": { "get": { "operationId": "listCustomers", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Customers:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List customers", "description": "Returns a list of all customers.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Customers:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create customer", "description": "Creates a new customer.\n", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Customers:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get customer", "description": "Returns a specific customer by ID.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Customers:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update customer", "description": "Updates an existing customer.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Customers:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete customer", "description": "Deletes a customer.\n", "tags": [ "Governance" ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Customers:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List teams attached to a customer", "tags": [ "Customers", "Teams" ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Customers:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List business units", "description": "Returns a paginated list of business units, each with its user count.\n", "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": [] }, { "BasicAuth": [] } ], "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" }, "user_count": { "type": "integer", "description": "Number of users that belong to this business unit." }, "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create business unit", "description": "Creates a new business unit. Names must be unique.\n", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create business unit request", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get business unit", "description": "Returns a specific business unit by ID, including governance and user count.\n", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Single business unit with governance and user count", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "user_count": { "type": "integer", "description": "Number of users that belong to this business unit." }, "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update business unit", "description": "Updates the business unit name.\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 request", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete business unit", "description": "Deletes a business unit. Every user membership of it is atomically removed as part of the\ndeletion, and each affected user's governance is refreshed so the business unit stops\napplying to their requests.\n", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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}/users": { "get": { "operationId": "listBusinessUnitUsers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List business unit users", "description": "Returns a paginated list of users that belong to the business unit, each with the\nprovenance of its membership edge so a caller can tell an admin assignment apart from\nan identity-provider-synced one.\n", "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 users to return (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "search", "in": "query", "description": "Case-insensitive search by user name or email", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated list of users that belong to a business unit", "required": [ "users", "count", "total_count", "limit", "offset" ], "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "source": { "type": "string", "description": "Provenance of this user's membership edge. `manual` means an admin or `config.json` assigned it and no claims sync will clear it; the synced values (`scim_user_attribute`, `scim_group_attribute`, `attribute_mapping`, `scim`) mean an identity provider owns it. Empty on legacy unstamped edges, which are treated as synced.\n" } } } }, "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": "assignUserToBusinessUnit", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Assign user to business unit", "description": "Assigns an existing user to the business unit. Membership is many-to-many, so a user may\nbelong to several business units and there is no conflict to reject.\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 user to a business unit", "required": [ "user_id" ], "properties": { "user_id": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "User 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 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/business-units/{business_unit_id}/users/{user_id}": { "delete": { "operationId": "removeUserFromBusinessUnit", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Remove user from business unit", "description": "Removes a user's membership of the business unit.\n", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "User 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": "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/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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete business unit governance", "description": "Removes all budget and rate limit governance from a business unit.\n", "tags": [ "Governance" ], "parameters": [ { "name": "business_unit_id", "in": "path", "required": true, "description": "Business unit ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `BusinessUnits:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Customer detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/governance/budgets": { "get": { "operationId": "listBudgets", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List budgets", "description": "Returns a list of all budgets. Use the `from_memory` query parameter to get data from in-memory cache.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List model limits", "description": "Returns a paginated list of model limits with their budget and rate limit settings.\n", "tags": [ "Governance" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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": "Comma-separated scopes to filter by. `project`, `access_profile` and the legacy `user` are Enterprise only.", "schema": { "type": "string" } }, { "name": "scope_id", "in": "query", "description": "Filter to one scope target, for example a project id. Pair it with `scope`.", "schema": { "type": "string" } }, { "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create model config", "description": "Creates a new model configuration with budget and rate limit settings.\n\n`scope: \"user\"` is rejected with 403. It is retired as a creatable scope — per-model\nbudgets for a person are now declared on an access profile and materialize per user as\n`access_profile`-scoped limits. Existing `user`-scoped rows keep working and stay editable\nthrough the update endpoint.\n", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModelConfigRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" } } } }, "403": { "description": "The requested scope cannot be assigned to a new limit. Returned for\n`scope: \"user\"`, which is retired in favour of access-profile per-model budgets.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/model-configs/{mc_id}": { "get": { "operationId": "getModelConfig", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get model config", "description": "Returns a specific model configuration by ID.\n", "tags": [ "Governance" ], "parameters": [ { "name": "mc_id", "in": "path", "required": true, "description": "Model config ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update model config", "description": "Updates an existing model configuration's budget and rate limit settings.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete model config", "description": "Deletes a model configuration.\n", "tags": [ "Governance" ], "parameters": [ { "name": "mc_id", "in": "path", "required": true, "description": "Model config ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List provider governance", "description": "Returns a list of all providers with their governance settings (budget and rate limits).\n", "tags": [ "Governance" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update provider governance", "description": "Updates governance settings (budget and rate limits) for a specific provider.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete provider governance", "description": "Removes governance settings (budget and rate limits) for a specific provider.\n", "tags": [ "Governance" ], "parameters": [ { "name": "provider_name", "in": "path", "required": true, "description": "Provider name", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List pricing overrides", "description": "Returns all pricing overrides, optionally filtered by scope.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create pricing override", "description": "Creates a new pricing override. The most specific matching scope always wins during cost resolution.\n", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePricingOverrideRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete pricing override", "description": "Deletes a pricing override by ID.\n", "tags": [ "Governance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pricing override ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List roles", "description": "Returns all roles visible to the caller, scoped by data access control.\n", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get role by ID", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List permissions assigned to a role", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List RBAC resources", "description": "Returns the set of resource names that permissions can target.\n", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List RBAC operations", "description": "Returns the set of operation names that permissions can grant.\n", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List all RBAC permissions", "description": "Returns every (resource, operation) pair that can be granted to a role.\n", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List access profiles", "description": "Returns access profiles visible to the caller.\n", "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": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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" }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "oneOf": [ { "type": "string", "description": "Rotation interval as a day count (\"30d\") or a Go duration (\"12h\", \"720h\"). Must resolve to between 1h and 365d. \"\" disables rotation.", "pattern": "^$|^[0-9]+d$|^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$", "example": "30d" }, { "type": "integer", "format": "int64", "description": "Rotation interval in nanoseconds. 0 disables rotation; otherwise between 1h (3600000000000) and 365d (31536000000000000).", "oneOf": [ { "const": 0 }, { "minimum": 3600000000000, "maximum": 31536000000000000 } ], "example": 2592000000000000 } ], "description": "Schedule automatic rotation of the profile's managed virtual keys. Accepts a day count (\"30d\"), a Go duration (\"12h\"), or integer nanoseconds. Between 1h and 365d; omit, \"\" or 0 to leave it off.", "example": "30d" }, "next_rotation_at": { "type": "string", "format": "date-time", "description": "Optional first rotation time; must be in the future and requires auto_rotation_interval. Defaults to now + interval." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get access profile by ID", "description": "Returns the profile plus its role attachments and the count of users holding a copy.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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 }, "allow_all_providers": { "type": "boolean", "nullable": true, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false, provider-wide access is disabled and access is deny-by-default via provider_configs. Omit to leave unchanged." }, "auto_rotation_interval": { "oneOf": [ { "type": "string", "description": "Rotation interval as a day count (\"30d\") or a Go duration (\"12h\", \"720h\"). Must resolve to between 1h and 365d. \"\" disables rotation.", "pattern": "^$|^[0-9]+d$|^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$", "example": "30d" }, { "type": "integer", "format": "int64", "description": "Rotation interval in nanoseconds. 0 disables rotation; otherwise between 1h (3600000000000) and 365d (31536000000000000).", "oneOf": [ { "const": 0 }, { "minimum": 3600000000000, "maximum": 31536000000000000 } ], "example": 2592000000000000 }, { "type": "null" } ], "description": "Replace the rotation schedule (\"30d\", \"12h\" or nanoseconds); \"\" or 0 turns it off. Omit to leave the schedule unchanged." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Override the next rotation time (must be in the future). null clears it, which is only valid when the interval is off. Omit to keep the existing schedule; a changed interval re-anchors it to now + interval." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete access profile", "description": "Blocked with 409 if any users still hold copies. Detach role attachments or remove user assignments first.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Activate access profile", "description": "Sets the profile active. Idempotent.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Deactivate access profile", "description": "Sets the profile inactive. Idempotent. User copies are preserved; the profile is hidden from selection menus.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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.\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": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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.\n", "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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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\n`budget_id` must be a budget on the user's own copy of the profile, not on the\nshared 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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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", "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": [] }, { "BasicAuth": [] } ], "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", "deprecated": true, "x-bifrost-successor": "/api/governance/users/{user_id}/virtual-keys", "x-bifrost-removal": "following-major-release", "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\n **Deprecated.** Use [`POST /api/governance/users/{user_id}/virtual-keys`](/api-reference/governance/mint-an-extra-virtual-key-for-a-user)\n instead. This path still works and behaves identically, but will be removed in a future major release.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Add an extra virtual key under a user's access profile (deprecated) (deprecated path)", "description": "Issues an additional virtual key for the user. \n\nVirtual keys are scoped to the **user**, not to one access profile: what a request may do with\nthe key is resolved at request time from whichever of the user's active profiles grant it. So\n`profile_id` is ignored — the key minted is the same whichever profile is named, and it is not\nbound to that profile or removed with it. The user must hold at least one access profile.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "description": "Ignored. Kept so the path shape stays valid for existing clients; keys are user-scoped, so any value produces the same result.\n", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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." } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User has no access profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "409": { "description": "A virtual key with this name already exists" }, "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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/governance/projects": { "get": { "operationId": "listProjects", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List projects", "description": "Returns projects visible to the caller: those they created, those with no\nrecorded creator, and those they belong to. Each project's roster is\nnarrowed the same way, so `members` is a subset of the true roster and\n`pagination.total` counts only what the caller may see.\n", "tags": [ "Projects" ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size, clamped to 100. Defaults to 20.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "One-based page number, consulted only when `offset` is absent.", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Case-insensitive match on name or description.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Return only enabled or only disabled projects.", "schema": { "type": "boolean" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "description": "A per-request access scope and accounting ledger that callers opt into with a header.", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "Globally unique. Requests reference it with the `x-bf-project-name` header." }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "default": true, "description": "A disabled project refuses every request that names it." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "An expired project refuses every request that names it. The comparison is inclusive." }, "access_rule": { "type": "string", "enum": [ "intersect", "union" ], "description": "How the project's own access composes with the access the caller already holds. `intersect` permits only what both allow, so a project with no provider config permits nothing. `union` leaves the caller's access untouched and adds to it, so a project with no provider or MCP config only attributes and caps spend." }, "membership_mode": { "type": "string", "enum": [ "explicit", "open" ], "default": "explicit", "description": "`explicit` admits only the users on the roster. `open` admits every authenticated caller and has no membership rows, which is why it cannot divide a budget between members." }, "accounting_mode": { "type": "string", "enum": [ "both", "project_only", "principal_only" ], "default": "both", "description": "Which ledgers a request's spend lands on. `both` charges the project and the caller. `project_only` takes the request off everything the caller funds, including the teams and business units above them. `principal_only` leaves the project's caps on record but checks and charges none of them. The deployment's own global caps always apply." }, "split_policy": { "type": "string", "enum": [ "none", "equal" ], "default": "none", "description": "`none` keeps the project's caps shared, and individual members can still be capped by hand. `equal` gives every member an equal slice of every budget and rate limit the project holds, at every tier, as a second cap within it." }, "calendar_aligned": { "type": "boolean", "default": false, "description": "Snaps every window the project holds, including each member's derived slice, onto calendar boundaries instead of running from creation." }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. Listed providers keep their own model, key, budget, and rate-limit rules." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "provider_configs": { "type": "array", "items": { "type": "object", "description": "What the project allows on one provider, and the money that provider's use answers to. A project names each provider at most once.", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place. An id the project does not hold is refused." }, "provider_name": { "type": "string", "example": "openai" }, "all_models_allowed": { "type": "boolean", "default": false, "description": "Allows every model the provider offers." }, "allowed_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Allowlist. `[\"*\"]` allows every model. A list may not mix `*` with named entries. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks everything. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "key_ids": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Provider keys that may serve the request. `[\"*\"]` allows all; an empty list allows none. Each id must exist and belong to this provider." }, "weight": { "type": "number", "nullable": true, "description": "Load-balancing preference for this provider inside the project. Null leaves the caller's own preference standing. Negative values are refused." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "model_budgets": { "type": "array", "items": { "type": "object", "description": "Caps for one model under a provider configuration. A provider may carry up to 100 of these, and the `*` tier is not accepted here because the provider configuration's own caps cover it.", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "Concrete model name. `*` is refused." }, "budgets": { "type": "array", "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "additionalProperties": false }, "description": "Per-model caps under this provider. Stored as project-scoped model configurations and reassembled on read, so this field is absent from `GET /api/governance/users/{user_id}/projects`." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the project may execute. Naming a client with an empty tool list still counts as the project having named it, so a client the project closes off cannot be reopened by a default-allowed rule.", "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place." }, "mcp_client_id": { "type": "integer", "description": "The stored MCP client. May be omitted when `mcp_client_name` is given, which is resolved to this id on write." }, "mcp_client_name": { "type": "string", "description": "Write-only convenience. Resolved to `mcp_client_id`; a name that matches no client is refused. Never returned on a read." }, "mcp_client": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/MCPClient" } ], "description": "The resolved client, included on reads." }, "tools_to_execute": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "`[\"*\"]` allows every tool the client exposes, including ones added later. An empty list allows none. A list may not mix `*` with named entries." } } } }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP assigned to the project. A scoped request can reach each one at its `/mcp/` endpoint. Assignments are a set, so a repeat collapses rather than doubling, and the list is replaced wholesale on update rather than diffed.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } }, "additionalProperties": false } }, "members": { "type": "array", "readOnly": true, "items": { "type": "object", "description": "A user on a project's roster. Members are users, never keys or teams: a key authenticates a request, and the user behind it is who belongs to a project.", "required": [ "user_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The membership row id, which is the `{member_id}` of the member routes." }, "user_id": { "type": "string", "description": "Immutable after creation. Changing it is a remove and an add." }, "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "user_name": { "type": "string", "readOnly": true }, "user_email": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "description": "Narrowed to what the caller's data access permits, so two operators can read the same project and see different rosters. Managed through the member routes, never through the project body." }, "created_by_user_id": { "type": "string", "nullable": true, "readOnly": true, "description": "Taken from the calling identity, never from the body." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "format": "int64", "description": "Matching projects visible to the caller, before pagination." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "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": "createProject", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create project", "description": "Creates a project. `access_rule` is required and has no default, since a\nrule that could be assumed might widen a request. The project starts with\nno members: add the roster through the member routes.\n", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A project starts with no members: the roster is written through the member routes, so this body has no `members` field.", "required": [ "name", "access_rule" ], "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "default": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "access_rule": { "type": "string", "enum": [ "intersect", "union" ], "description": "How the project's own access composes with the access the caller already holds. `intersect` permits only what both allow, so a project with no provider config permits nothing. `union` leaves the caller's access untouched and adds to it, so a project with no provider or MCP config only attributes and caps spend." }, "membership_mode": { "type": "string", "enum": [ "explicit", "open" ], "default": "explicit", "description": "`explicit` admits only the users on the roster. `open` admits every authenticated caller and has no membership rows, which is why it cannot divide a budget between members." }, "accounting_mode": { "type": "string", "enum": [ "both", "project_only", "principal_only" ], "default": "both", "description": "Which ledgers a request's spend lands on. `both` charges the project and the caller. `project_only` takes the request off everything the caller funds, including the teams and business units above them. `principal_only` leaves the project's caps on record but checks and charges none of them. The deployment's own global caps always apply." }, "split_policy": { "type": "string", "enum": [ "none", "equal" ], "default": "none", "description": "`none` keeps the project's caps shared, and individual members can still be capped by hand. `equal` gives every member an equal slice of every budget and rate limit the project holds, at every tier, as a second cap within it." }, "calendar_aligned": { "type": "boolean", "default": false }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. Listed providers keep their own model, key, budget, and rate-limit rules." }, "budgets": { "type": "array", "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "provider_configs": { "type": "array", "items": { "type": "object", "description": "What the project allows on one provider, and the money that provider's use answers to. A project names each provider at most once.", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place. An id the project does not hold is refused." }, "provider_name": { "type": "string", "example": "openai" }, "all_models_allowed": { "type": "boolean", "default": false, "description": "Allows every model the provider offers." }, "allowed_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Allowlist. `[\"*\"]` allows every model. A list may not mix `*` with named entries. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks everything. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "key_ids": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Provider keys that may serve the request. `[\"*\"]` allows all; an empty list allows none. Each id must exist and belong to this provider." }, "weight": { "type": "number", "nullable": true, "description": "Load-balancing preference for this provider inside the project. Null leaves the caller's own preference standing. Negative values are refused." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "model_budgets": { "type": "array", "items": { "type": "object", "description": "Caps for one model under a provider configuration. A provider may carry up to 100 of these, and the `*` tier is not accepted here because the provider configuration's own caps cover it.", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "Concrete model name. `*` is refused." }, "budgets": { "type": "array", "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "additionalProperties": false }, "description": "Per-model caps under this provider. Stored as project-scoped model configurations and reassembled on read, so this field is absent from `GET /api/governance/users/{user_id}/projects`." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the project may execute. Naming a client with an empty tool list still counts as the project having named it, so a client the project closes off cannot be reopened by a default-allowed rule.", "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place." }, "mcp_client_id": { "type": "integer", "description": "The stored MCP client. May be omitted when `mcp_client_name` is given, which is resolved to this id on write." }, "mcp_client_name": { "type": "string", "description": "Write-only convenience. Resolved to `mcp_client_id`; a name that matches no client is refused. Never returned on a read." }, "mcp_client": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/MCPClient" } ], "description": "The resolved client, included on reads." }, "tools_to_execute": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "`[\"*\"]` allows every tool the client exposes, including ones added later. An empty list allows none. A list may not mix `*` with named entries." } } } }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP assigned to the project. A scoped request can reach each one at its `/mcp/` endpoint. Assignments are a set, so a repeat collapses rather than doubling, and the list is replaced wholesale on update rather than diffed.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "description": "A per-request access scope and accounting ledger that callers opt into with a header.", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "Globally unique. Requests reference it with the `x-bf-project-name` header." }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "default": true, "description": "A disabled project refuses every request that names it." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "An expired project refuses every request that names it. The comparison is inclusive." }, "access_rule": { "type": "string", "enum": [ "intersect", "union" ], "description": "How the project's own access composes with the access the caller already holds. `intersect` permits only what both allow, so a project with no provider config permits nothing. `union` leaves the caller's access untouched and adds to it, so a project with no provider or MCP config only attributes and caps spend." }, "membership_mode": { "type": "string", "enum": [ "explicit", "open" ], "default": "explicit", "description": "`explicit` admits only the users on the roster. `open` admits every authenticated caller and has no membership rows, which is why it cannot divide a budget between members." }, "accounting_mode": { "type": "string", "enum": [ "both", "project_only", "principal_only" ], "default": "both", "description": "Which ledgers a request's spend lands on. `both` charges the project and the caller. `project_only` takes the request off everything the caller funds, including the teams and business units above them. `principal_only` leaves the project's caps on record but checks and charges none of them. The deployment's own global caps always apply." }, "split_policy": { "type": "string", "enum": [ "none", "equal" ], "default": "none", "description": "`none` keeps the project's caps shared, and individual members can still be capped by hand. `equal` gives every member an equal slice of every budget and rate limit the project holds, at every tier, as a second cap within it." }, "calendar_aligned": { "type": "boolean", "default": false, "description": "Snaps every window the project holds, including each member's derived slice, onto calendar boundaries instead of running from creation." }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. Listed providers keep their own model, key, budget, and rate-limit rules." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "provider_configs": { "type": "array", "items": { "type": "object", "description": "What the project allows on one provider, and the money that provider's use answers to. A project names each provider at most once.", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place. An id the project does not hold is refused." }, "provider_name": { "type": "string", "example": "openai" }, "all_models_allowed": { "type": "boolean", "default": false, "description": "Allows every model the provider offers." }, "allowed_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Allowlist. `[\"*\"]` allows every model. A list may not mix `*` with named entries. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks everything. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "key_ids": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Provider keys that may serve the request. `[\"*\"]` allows all; an empty list allows none. Each id must exist and belong to this provider." }, "weight": { "type": "number", "nullable": true, "description": "Load-balancing preference for this provider inside the project. Null leaves the caller's own preference standing. Negative values are refused." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "model_budgets": { "type": "array", "items": { "type": "object", "description": "Caps for one model under a provider configuration. A provider may carry up to 100 of these, and the `*` tier is not accepted here because the provider configuration's own caps cover it.", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "Concrete model name. `*` is refused." }, "budgets": { "type": "array", "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "additionalProperties": false }, "description": "Per-model caps under this provider. Stored as project-scoped model configurations and reassembled on read, so this field is absent from `GET /api/governance/users/{user_id}/projects`." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the project may execute. Naming a client with an empty tool list still counts as the project having named it, so a client the project closes off cannot be reopened by a default-allowed rule.", "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place." }, "mcp_client_id": { "type": "integer", "description": "The stored MCP client. May be omitted when `mcp_client_name` is given, which is resolved to this id on write." }, "mcp_client_name": { "type": "string", "description": "Write-only convenience. Resolved to `mcp_client_id`; a name that matches no client is refused. Never returned on a read." }, "mcp_client": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/MCPClient" } ], "description": "The resolved client, included on reads." }, "tools_to_execute": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "`[\"*\"]` allows every tool the client exposes, including ones added later. An empty list allows none. A list may not mix `*` with named entries." } } } }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP assigned to the project. A scoped request can reach each one at its `/mcp/` endpoint. Assignments are a set, so a repeat collapses rather than doubling, and the list is replaced wholesale on update rather than diffed.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } }, "additionalProperties": false } }, "members": { "type": "array", "readOnly": true, "items": { "type": "object", "description": "A user on a project's roster. Members are users, never keys or teams: a key authenticates a request, and the user behind it is who belongs to a project.", "required": [ "user_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The membership row id, which is the `{member_id}` of the member routes." }, "user_id": { "type": "string", "description": "Immutable after creation. Changing it is a remove and an add." }, "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "user_name": { "type": "string", "readOnly": true }, "user_email": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "description": "Narrowed to what the caller's data access permits, so two operators can read the same project and see different rosters. Managed through the member routes, never through the project body." }, "created_by_user_id": { "type": "string", "nullable": true, "readOnly": true, "description": "Taken from the calling identity, never from the body." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "A project with the same name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/projects/{project_id}": { "get": { "operationId": "getProject", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get project", "description": "Returns one project with its caps, its provider and MCP access, and the\npart of its roster the caller may see. A project outside the caller's data\naccess reads as not found rather than forbidden.\n", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "description": "A per-request access scope and accounting ledger that callers opt into with a header.", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "Globally unique. Requests reference it with the `x-bf-project-name` header." }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "default": true, "description": "A disabled project refuses every request that names it." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "An expired project refuses every request that names it. The comparison is inclusive." }, "access_rule": { "type": "string", "enum": [ "intersect", "union" ], "description": "How the project's own access composes with the access the caller already holds. `intersect` permits only what both allow, so a project with no provider config permits nothing. `union` leaves the caller's access untouched and adds to it, so a project with no provider or MCP config only attributes and caps spend." }, "membership_mode": { "type": "string", "enum": [ "explicit", "open" ], "default": "explicit", "description": "`explicit` admits only the users on the roster. `open` admits every authenticated caller and has no membership rows, which is why it cannot divide a budget between members." }, "accounting_mode": { "type": "string", "enum": [ "both", "project_only", "principal_only" ], "default": "both", "description": "Which ledgers a request's spend lands on. `both` charges the project and the caller. `project_only` takes the request off everything the caller funds, including the teams and business units above them. `principal_only` leaves the project's caps on record but checks and charges none of them. The deployment's own global caps always apply." }, "split_policy": { "type": "string", "enum": [ "none", "equal" ], "default": "none", "description": "`none` keeps the project's caps shared, and individual members can still be capped by hand. `equal` gives every member an equal slice of every budget and rate limit the project holds, at every tier, as a second cap within it." }, "calendar_aligned": { "type": "boolean", "default": false, "description": "Snaps every window the project holds, including each member's derived slice, onto calendar boundaries instead of running from creation." }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. Listed providers keep their own model, key, budget, and rate-limit rules." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "provider_configs": { "type": "array", "items": { "type": "object", "description": "What the project allows on one provider, and the money that provider's use answers to. A project names each provider at most once.", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place. An id the project does not hold is refused." }, "provider_name": { "type": "string", "example": "openai" }, "all_models_allowed": { "type": "boolean", "default": false, "description": "Allows every model the provider offers." }, "allowed_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Allowlist. `[\"*\"]` allows every model. A list may not mix `*` with named entries. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks everything. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "key_ids": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Provider keys that may serve the request. `[\"*\"]` allows all; an empty list allows none. Each id must exist and belong to this provider." }, "weight": { "type": "number", "nullable": true, "description": "Load-balancing preference for this provider inside the project. Null leaves the caller's own preference standing. Negative values are refused." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "model_budgets": { "type": "array", "items": { "type": "object", "description": "Caps for one model under a provider configuration. A provider may carry up to 100 of these, and the `*` tier is not accepted here because the provider configuration's own caps cover it.", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "Concrete model name. `*` is refused." }, "budgets": { "type": "array", "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "additionalProperties": false }, "description": "Per-model caps under this provider. Stored as project-scoped model configurations and reassembled on read, so this field is absent from `GET /api/governance/users/{user_id}/projects`." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the project may execute. Naming a client with an empty tool list still counts as the project having named it, so a client the project closes off cannot be reopened by a default-allowed rule.", "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place." }, "mcp_client_id": { "type": "integer", "description": "The stored MCP client. May be omitted when `mcp_client_name` is given, which is resolved to this id on write." }, "mcp_client_name": { "type": "string", "description": "Write-only convenience. Resolved to `mcp_client_id`; a name that matches no client is refused. Never returned on a read." }, "mcp_client": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/MCPClient" } ], "description": "The resolved client, included on reads." }, "tools_to_execute": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "`[\"*\"]` allows every tool the client exposes, including ones added later. An empty list allows none. A list may not mix `*` with named entries." } } } }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP assigned to the project. A scoped request can reach each one at its `/mcp/` endpoint. Assignments are a set, so a repeat collapses rather than doubling, and the list is replaced wholesale on update rather than diffed.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } }, "additionalProperties": false } }, "members": { "type": "array", "readOnly": true, "items": { "type": "object", "description": "A user on a project's roster. Members are users, never keys or teams: a key authenticates a request, and the user behind it is who belongs to a project.", "required": [ "user_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The membership row id, which is the `{member_id}` of the member routes." }, "user_id": { "type": "string", "description": "Immutable after creation. Changing it is a remove and an add." }, "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "user_name": { "type": "string", "readOnly": true }, "user_email": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "description": "Narrowed to what the caller's data access permits, so two operators can read the same project and see different rosters. Managed through the member routes, never through the project body." }, "created_by_user_id": { "type": "string", "nullable": true, "readOnly": true, "description": "Taken from the calling identity, never from the body." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Project not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "put": { "operationId": "updateProject", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update project", "description": "Applies a patch to the stored project. Fields the body omits are left as\nstored, and child lists are paired with their stored rows by `id`, so a\ncap keeps its accumulated spend and its window across an edit while a\nchild the body stops naming is deleted.\n\nChanging the roster or any divided cap on a project with\n`split_policy: equal` recalculates every member's slice. That work is\nqueued and its id is returned as `redivision_job_id`; the project's own\nwrite has already committed by then, so a failure to queue is reported as\na server error rather than rolling the edit back.\n", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Read-then-patch. A field this body omits is left as stored. For `description`, `expires_at`, `rate_limit`, `budgets`, `provider_configs`, `mcp_configs` and `virtual_mcps`, an explicit `null` clears what is stored, and for the four list fields that means deleting every stored child. The remaining fields cannot be cleared: `null` reads the same as omitted. Child lists are matched to their stored rows by `id`, so restate the ids you read; a stored child the body does not name is deleted. A `members` field is ignored rather than refused.", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "access_rule": { "type": "string", "enum": [ "intersect", "union" ], "description": "How the project's own access composes with the access the caller already holds. `intersect` permits only what both allow, so a project with no provider config permits nothing. `union` leaves the caller's access untouched and adds to it, so a project with no provider or MCP config only attributes and caps spend." }, "membership_mode": { "type": "string", "enum": [ "explicit", "open" ], "default": "explicit", "description": "`explicit` admits only the users on the roster. `open` admits every authenticated caller and has no membership rows, which is why it cannot divide a budget between members." }, "accounting_mode": { "type": "string", "enum": [ "both", "project_only", "principal_only" ], "default": "both", "description": "Which ledgers a request's spend lands on. `both` charges the project and the caller. `project_only` takes the request off everything the caller funds, including the teams and business units above them. `principal_only` leaves the project's caps on record but checks and charges none of them. The deployment's own global caps always apply." }, "split_policy": { "type": "string", "enum": [ "none", "equal" ], "default": "none", "description": "`none` keeps the project's caps shared, and individual members can still be capped by hand. `equal` gives every member an equal slice of every budget and rate limit the project holds, at every tier, as a second cap within it." }, "calendar_aligned": { "type": "boolean" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. Listed providers keep their own model, key, budget, and rate-limit rules. Omit to leave unchanged." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "oneOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, { "type": "null" } ] }, "provider_configs": { "type": "array", "nullable": true, "items": { "type": "object", "description": "What the project allows on one provider, and the money that provider's use answers to. A project names each provider at most once.", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place. An id the project does not hold is refused." }, "provider_name": { "type": "string", "example": "openai" }, "all_models_allowed": { "type": "boolean", "default": false, "description": "Allows every model the provider offers." }, "allowed_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Allowlist. `[\"*\"]` allows every model. A list may not mix `*` with named entries. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks everything. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "key_ids": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Provider keys that may serve the request. `[\"*\"]` allows all; an empty list allows none. Each id must exist and belong to this provider." }, "weight": { "type": "number", "nullable": true, "description": "Load-balancing preference for this provider inside the project. Null leaves the caller's own preference standing. Negative values are refused." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "model_budgets": { "type": "array", "items": { "type": "object", "description": "Caps for one model under a provider configuration. A provider may carry up to 100 of these, and the `*` tier is not accepted here because the provider configuration's own caps cover it.", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "Concrete model name. `*` is refused." }, "budgets": { "type": "array", "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "additionalProperties": false }, "description": "Per-model caps under this provider. Stored as project-scoped model configurations and reassembled on read, so this field is absent from `GET /api/governance/users/{user_id}/projects`." } } } }, "mcp_configs": { "type": "array", "nullable": true, "items": { "type": "object", "description": "The tools of one MCP client the project may execute. Naming a client with an empty tool list still counts as the project having named it, so a client the project closes off cannot be reopened by a default-allowed rule.", "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place." }, "mcp_client_id": { "type": "integer", "description": "The stored MCP client. May be omitted when `mcp_client_name` is given, which is resolved to this id on write." }, "mcp_client_name": { "type": "string", "description": "Write-only convenience. Resolved to `mcp_client_id`; a name that matches no client is refused. Never returned on a read." }, "mcp_client": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/MCPClient" } ], "description": "The resolved client, included on reads." }, "tools_to_execute": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "`[\"*\"]` allows every tool the client exposes, including ones added later. An empty list allows none. A list may not mix `*` with named entries." } } } }, "virtual_mcps": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A Virtual MCP assigned to the project. A scoped request can reach each one at its `/mcp/` endpoint. Assignments are a set, so a repeat collapses rather than doubling, and the list is replaced wholesale on update rather than diffed.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } }, "additionalProperties": false } }, "reset_budget_usage": { "type": "boolean", "description": "Clears recorded spend on the budgets this body restates that the project already held, and on each member's slice of them. A budget the edit introduces has no spend to clear, and one the body does not name is left alone." } }, "additionalProperties": false } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Project updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "description": "A per-request access scope and accounting ledger that callers opt into with a header.", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "Globally unique. Requests reference it with the `x-bf-project-name` header." }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "default": true, "description": "A disabled project refuses every request that names it." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "An expired project refuses every request that names it. The comparison is inclusive." }, "access_rule": { "type": "string", "enum": [ "intersect", "union" ], "description": "How the project's own access composes with the access the caller already holds. `intersect` permits only what both allow, so a project with no provider config permits nothing. `union` leaves the caller's access untouched and adds to it, so a project with no provider or MCP config only attributes and caps spend." }, "membership_mode": { "type": "string", "enum": [ "explicit", "open" ], "default": "explicit", "description": "`explicit` admits only the users on the roster. `open` admits every authenticated caller and has no membership rows, which is why it cannot divide a budget between members." }, "accounting_mode": { "type": "string", "enum": [ "both", "project_only", "principal_only" ], "default": "both", "description": "Which ledgers a request's spend lands on. `both` charges the project and the caller. `project_only` takes the request off everything the caller funds, including the teams and business units above them. `principal_only` leaves the project's caps on record but checks and charges none of them. The deployment's own global caps always apply." }, "split_policy": { "type": "string", "enum": [ "none", "equal" ], "default": "none", "description": "`none` keeps the project's caps shared, and individual members can still be capped by hand. `equal` gives every member an equal slice of every budget and rate limit the project holds, at every tier, as a second cap within it." }, "calendar_aligned": { "type": "boolean", "default": false, "description": "Snaps every window the project holds, including each member's derived slice, onto calendar boundaries instead of running from creation." }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. Listed providers keep their own model, key, budget, and rate-limit rules." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "provider_configs": { "type": "array", "items": { "type": "object", "description": "What the project allows on one provider, and the money that provider's use answers to. A project names each provider at most once.", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place. An id the project does not hold is refused." }, "provider_name": { "type": "string", "example": "openai" }, "all_models_allowed": { "type": "boolean", "default": false, "description": "Allows every model the provider offers." }, "allowed_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Allowlist. `[\"*\"]` allows every model. A list may not mix `*` with named entries. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks everything. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "key_ids": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Provider keys that may serve the request. `[\"*\"]` allows all; an empty list allows none. Each id must exist and belong to this provider." }, "weight": { "type": "number", "nullable": true, "description": "Load-balancing preference for this provider inside the project. Null leaves the caller's own preference standing. Negative values are refused." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "model_budgets": { "type": "array", "items": { "type": "object", "description": "Caps for one model under a provider configuration. A provider may carry up to 100 of these, and the `*` tier is not accepted here because the provider configuration's own caps cover it.", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "Concrete model name. `*` is refused." }, "budgets": { "type": "array", "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "additionalProperties": false }, "description": "Per-model caps under this provider. Stored as project-scoped model configurations and reassembled on read, so this field is absent from `GET /api/governance/users/{user_id}/projects`." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the project may execute. Naming a client with an empty tool list still counts as the project having named it, so a client the project closes off cannot be reopened by a default-allowed rule.", "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place." }, "mcp_client_id": { "type": "integer", "description": "The stored MCP client. May be omitted when `mcp_client_name` is given, which is resolved to this id on write." }, "mcp_client_name": { "type": "string", "description": "Write-only convenience. Resolved to `mcp_client_id`; a name that matches no client is refused. Never returned on a read." }, "mcp_client": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/MCPClient" } ], "description": "The resolved client, included on reads." }, "tools_to_execute": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "`[\"*\"]` allows every tool the client exposes, including ones added later. An empty list allows none. A list may not mix `*` with named entries." } } } }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP assigned to the project. A scoped request can reach each one at its `/mcp/` endpoint. Assignments are a set, so a repeat collapses rather than doubling, and the list is replaced wholesale on update rather than diffed.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } }, "additionalProperties": false } }, "members": { "type": "array", "readOnly": true, "items": { "type": "object", "description": "A user on a project's roster. Members are users, never keys or teams: a key authenticates a request, and the user behind it is who belongs to a project.", "required": [ "user_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The membership row id, which is the `{member_id}` of the member routes." }, "user_id": { "type": "string", "description": "Immutable after creation. Changing it is a remove and an add." }, "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "user_name": { "type": "string", "readOnly": true }, "user_email": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "description": "Narrowed to what the caller's data access permits, so two operators can read the same project and see different rosters. Managed through the member routes, never through the project body." }, "created_by_user_id": { "type": "string", "nullable": true, "readOnly": true, "description": "Taken from the calling identity, never from the body." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "redivision_job_id": { "type": "string", "description": "Present only when the edit queued a redivision, which happens on a project with `split_policy: equal` whose roster or divided caps changed. A pending job for the same project is reused rather than queued behind, so this may name a job an earlier request created. Progress is reported on the `redivision_progress` WebSocket channel under this id." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Project not found" }, "409": { "description": "A project with the same name already exists." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "deleteProject", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete project", "description": "Deletes the project with its providers, its caps, the spend recorded\nagainst them, and its roster. A roster is not a reason to refuse, so there\nis no force flag. Log rows keep the attribution they already carry.\n", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Project deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "project deleted" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Project not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/projects/{project_id}/members": { "get": { "operationId": "listProjectMembers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List project members", "description": "Returns the roster with each member's caps, narrowed to what the caller's\ndata access permits. There is no pagination on this route.\n", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "description": "A user on a project's roster. Members are users, never keys or teams: a key authenticates a request, and the user behind it is who belongs to a project.", "required": [ "user_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The membership row id, which is the `{member_id}` of the member routes." }, "user_id": { "type": "string", "description": "Immutable after creation. Changing it is a remove and an add." }, "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "user_name": { "type": "string", "readOnly": true }, "user_email": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Project not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "post": { "operationId": "addProjectMembers", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Add project members", "description": "Adds users to the roster. The call is create-only: a user already on the\nroster keeps their existing membership and caps.\n\nOn a project with `split_policy: equal` the addition shrinks every\nmember's slice of every cap, so a rate limit that cannot be divided into\nwhole units for the resulting roster is refused before anything is\nwritten, and the recalculation is queued and reported as\n`redivision_job_id`.\n", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create-only. A user already on the roster keeps their existing membership and caps, and the entry for them is discarded.", "required": [ "members" ], "properties": { "members": { "type": "array", "minItems": 1, "items": { "type": "object", "description": "A user on a project's roster. Members are users, never keys or teams: a key authenticates a request, and the user behind it is who belongs to a project.", "required": [ "user_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The membership row id, which is the `{member_id}` of the member routes." }, "user_id": { "type": "string", "description": "Immutable after creation. Changing it is a remove and an add." }, "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "user_name": { "type": "string", "readOnly": true }, "user_email": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } } }, "additionalProperties": false } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "201": { "description": "Members added", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "2 member(s) added", "description": "Counts the entries submitted, including any already on the roster." }, "redivision_job_id": { "type": "string", "description": "Present only on a project with `split_policy: equal`, whose every member's slice of every cap is recalculated in the background." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Project not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/projects/{project_id}/members/{member_id}": { "put": { "operationId": "updateProjectMember", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update project member caps", "description": "Restates one member's caps in full: a source the body does not name loses\nits cap, and an empty body clears every cap the member holds. The member's\nidentity is not editable.\n\nOnly available on a project with `split_policy: none`. Under an equal\nsplit the division owns those rows, and the request is refused before the\nbody is read. `{member_id}` is the membership row id, and a member outside\nthe caller's data access reads as not found.\n", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "member_id", "in": "path", "required": true, "description": "The membership row id, not the user id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The member's complete statement of caps. A source this body does not name loses its cap, and an empty body clears every cap the member holds. Only available on a project with `split_policy: none`.", "properties": { "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } } }, "additionalProperties": false } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Member updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "description": "A user on a project's roster. Members are users, never keys or teams: a key authenticates a request, and the user behind it is who belongs to a project.", "required": [ "user_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The membership row id, which is the `{member_id}` of the member routes." }, "user_id": { "type": "string", "description": "Immutable after creation. Changing it is a remove and an add." }, "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "user_name": { "type": "string", "readOnly": true }, "user_email": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Project or member not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } }, "delete": { "operationId": "removeProjectMember", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Remove project member", "description": "Removes a member from the roster and deletes the caps derived for them. On\na project with `split_policy: equal` this enlarges every remaining\nmember's slice, and the recalculation is queued and reported as\n`redivision_job_id`.\n", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "member_id", "in": "path", "required": true, "description": "The membership row id, not the user id.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Member removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "project member removed" }, "redivision_job_id": { "type": "string", "description": "Present only on a project with `split_policy: equal`, where removal enlarges every remaining member's slice." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Project or member not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/users/{user_id}/projects": { "get": { "operationId": "listUserProjects", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Projects:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List a user's projects", "description": "Returns the projects the named user belongs to, intersected with the\nprojects the caller may see, so asking about a user reveals nothing the\ncaller could not already read. An unknown user returns an empty list\nrather than a not-found error.\n\nThis listing is assembled without the per-model caps, the member shares\nand the member display names; read a project directly for those.\n", "tags": [ "Projects" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Projects the named user belongs to that the caller may also see. This listing is assembled without the per-model caps, the member shares or the member display names, so `provider_configs[].model_budgets`, `members[].budget_shares`, `members[].rate_limit_shares`, `members[].user_name` and `members[].user_email` are absent.", "properties": { "projects": { "type": "array", "items": { "type": "object", "description": "A per-request access scope and accounting ledger that callers opt into with a header.", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "Globally unique. Requests reference it with the `x-bf-project-name` header." }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "default": true, "description": "A disabled project refuses every request that names it." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "An expired project refuses every request that names it. The comparison is inclusive." }, "access_rule": { "type": "string", "enum": [ "intersect", "union" ], "description": "How the project's own access composes with the access the caller already holds. `intersect` permits only what both allow, so a project with no provider config permits nothing. `union` leaves the caller's access untouched and adds to it, so a project with no provider or MCP config only attributes and caps spend." }, "membership_mode": { "type": "string", "enum": [ "explicit", "open" ], "default": "explicit", "description": "`explicit` admits only the users on the roster. `open` admits every authenticated caller and has no membership rows, which is why it cannot divide a budget between members." }, "accounting_mode": { "type": "string", "enum": [ "both", "project_only", "principal_only" ], "default": "both", "description": "Which ledgers a request's spend lands on. `both` charges the project and the caller. `project_only` takes the request off everything the caller funds, including the teams and business units above them. `principal_only` leaves the project's caps on record but checks and charges none of them. The deployment's own global caps always apply." }, "split_policy": { "type": "string", "enum": [ "none", "equal" ], "default": "none", "description": "`none` keeps the project's caps shared, and individual members can still be capped by hand. `equal` gives every member an equal slice of every budget and rate limit the project holds, at every tier, as a second cap within it." }, "calendar_aligned": { "type": "boolean", "default": false, "description": "Snaps every window the project holds, including each member's derived slice, onto calendar boundaries instead of running from creation." }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. Listed providers keep their own model, key, budget, and rate-limit rules." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "provider_configs": { "type": "array", "items": { "type": "object", "description": "What the project allows on one provider, and the money that provider's use answers to. A project names each provider at most once.", "required": [ "provider_name" ], "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place. An id the project does not hold is refused." }, "provider_name": { "type": "string", "example": "openai" }, "all_models_allowed": { "type": "boolean", "default": false, "description": "Allows every model the provider offers." }, "allowed_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Allowlist. `[\"*\"]` allows every model. A list may not mix `*` with named entries. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks everything. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "key_ids": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Provider keys that may serve the request. `[\"*\"]` allows all; an empty list allows none. Each id must exist and belong to this provider." }, "weight": { "type": "number", "nullable": true, "description": "Load-balancing preference for this provider inside the project. Null leaves the caller's own preference standing. Negative values are refused." }, "budgets": { "type": "array", "nullable": true, "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "model_budgets": { "type": "array", "items": { "type": "object", "description": "Caps for one model under a provider configuration. A provider may carry up to 100 of these, and the `*` tier is not accepted here because the provider configuration's own caps cover it.", "required": [ "model_name" ], "properties": { "model_name": { "type": "string", "description": "Concrete model name. `*` is refused." }, "budgets": { "type": "array", "items": { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit": { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "additionalProperties": false }, "description": "Per-model caps under this provider. Stored as project-scoped model configurations and reassembled on read, so this field is absent from `GET /api/governance/users/{user_id}/projects`." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the project may execute. Naming a client with an empty tool list still counts as the project having named it, so a client the project closes off cannot be reopened by a default-allowed rule.", "properties": { "id": { "type": "integer", "description": "Omit or send `0` to create. Restate to update in place." }, "mcp_client_id": { "type": "integer", "description": "The stored MCP client. May be omitted when `mcp_client_name` is given, which is resolved to this id on write." }, "mcp_client_name": { "type": "string", "description": "Write-only convenience. Resolved to `mcp_client_id`; a name that matches no client is refused. Never returned on a read." }, "mcp_client": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/MCPClient" } ], "description": "The resolved client, included on reads." }, "tools_to_execute": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "`[\"*\"]` allows every tool the client exposes, including ones added later. An empty list allows none. A list may not mix `*` with named entries." } } } }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP assigned to the project. A scoped request can reach each one at its `/mcp/` endpoint. Assignments are a set, so a repeat collapses rather than doubling, and the list is replaced wholesale on update rather than diffed.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } }, "additionalProperties": false } }, "members": { "type": "array", "readOnly": true, "items": { "type": "object", "description": "A user on a project's roster. Members are users, never keys or teams: a key authenticates a request, and the user behind it is who belongs to a project.", "required": [ "user_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The membership row id, which is the `{member_id}` of the member routes." }, "user_id": { "type": "string", "description": "Immutable after creation. Changing it is a remove and an add." }, "budget_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a budget the project holds. The share is a second cap, not a replacement: the budget it slices still caps the whole, and whichever binds first refuses the request.", "required": [ "source_budget_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_budget_id": { "type": "string", "description": "The budget being sliced. Must be one the project holds, at any tier." }, "budget_id": { "type": "string", "readOnly": true, "description": "The derived governance budget that enforces the slice." }, "share_value": { "type": "number", "description": "The authored figure. A percent share must be greater than 0 and at most 100; an amount share must be greater than 0. Null on every slice derived by an equal split." }, "share_type": { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." }, "budget": { "readOnly": true, "allOf": [ { "type": "object", "description": "A spend cap on a project, on a provider inside it, or on a model under that provider. On an update, restating `id` pairs the declaration with its stored row so accumulated spend and the window anchor carry over; omit `id` to create a new cap.", "required": [ "max_limit", "reset_duration" ], "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place. An id the project does not hold is refused." }, "max_limit": { "type": "number", "minimum": 0, "description": "Cap in dollars." }, "reset_duration": { "type": "string", "description": "Reset window as a number and a unit, for example `30s`, `5m`, `1h`, `1d`, `1w`, `1M`, `1Q`, `1Y`. Only day-or-longer windows can be calendar-aligned.", "example": "1M" }, "reset_config": { "type": "object", "description": "Window settings the reset duration cannot express. Only valid when `reset_duration` is quarterly (`1Q`).", "properties": { "quarter_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "First month of Q1 as 1-12. Omitted means January. Only the value modulo 3 changes the reset dates, so January, April, July and October all reset on calendar quarters." } }, "additionalProperties": false }, "current_usage": { "type": "number", "readOnly": true, "description": "Spend recorded in the current window." }, "last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "override_amount": { "type": "number", "readOnly": true, "description": "Operator top-up added to `max_limit` while active. Projects have no endpoint that sets one; the field is reported for completeness." }, "override_mode": { "type": "string", "readOnly": true }, "override_cycles_remaining": { "type": "integer", "readOnly": true }, "override_cycles_total": { "type": "integer", "readOnly": true }, "override_anchor_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived budget row, with its own usage." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "rate_limit_shares": { "type": "array", "items": { "type": "object", "description": "One member's cap on a rate limit the project holds. The token and request dimensions are authored independently, so a member may hold a percentage of tokens and a flat count of requests.", "required": [ "source_rate_limit_id" ], "properties": { "id": { "type": "string", "readOnly": true }, "project_id": { "type": "string", "readOnly": true }, "user_id": { "type": "string", "readOnly": true }, "source_rate_limit_id": { "type": "string", "description": "The rate limit being sliced. Must be one the project holds, at any tier." }, "rate_limit_id": { "type": "string", "readOnly": true, "description": "The derived governance rate limit that enforces the slice." }, "token_share": { "type": "integer", "description": "Authored token share. Requires the source to cap tokens. A percent share that comes to no whole tokens is refused." }, "token_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a token share is given without one." }, "request_share": { "type": "integer", "description": "Authored request share. Requires the source to cap requests. A percent share that comes to no whole requests is refused." }, "request_share_type": { "allOf": [ { "type": "string", "enum": [ "percent", "amount" ], "description": "Whether a member's authored share is a percentage of the source cap or an absolute figure. Budget shares must state this explicitly; a rate-limit share left blank settles to `amount`." } ], "description": "Settles to `amount` when a request share is given without one." }, "rate_limit": { "readOnly": true, "allOf": [ { "type": "object", "description": "A token and request rate limit on a project, on a provider inside it, or on a model under that provider. The two dimensions run independent windows, and a cap is enforced only together with its window.", "properties": { "id": { "type": "string", "description": "Omit to create. Restate to update in place." }, "token_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum tokens per window. Requires `token_reset_duration`. On a project with `split_policy: equal`, a cap below the member count is refused, since a slice is a whole number of tokens." }, "token_reset_duration": { "type": "string", "example": "1h" }, "request_max_limit": { "type": "integer", "minimum": 0, "description": "Maximum requests per window. Requires `request_reset_duration`. Subject to the same lower bound under `split_policy: equal`." }, "request_reset_duration": { "type": "string", "example": "1h" }, "token_current_usage": { "type": "integer", "readOnly": true }, "token_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "request_current_usage": { "type": "integer", "readOnly": true }, "request_last_reset": { "type": "string", "format": "date-time", "readOnly": true }, "config_hash": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } ], "description": "The derived rate limit row, with its own counters." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } } }, "user_name": { "type": "string", "readOnly": true }, "user_email": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "description": "Narrowed to what the caller's data access permits, so two operators can read the same project and see different rosters. Managed through the member routes, never through the project body." }, "created_by_user_id": { "type": "string", "nullable": true, "readOnly": true, "description": "Taken from the calling identity, never from the body." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": 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" } } } } } } }, "/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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Customers:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List roles (deprecated path)", "description": "Returns all roles visible to the caller, scoped by data access control.\n", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get role by ID (deprecated path)", "tags": [ "RBAC" ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RBAC:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List RBAC resources (deprecated path)", "description": "Returns the set of resource names that permissions can target.\n", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List RBAC operations (deprecated path)", "description": "Returns the set of operation names that permissions can grant.\n", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List all RBAC permissions (deprecated path)", "description": "Returns every (resource, operation) pair that can be granted to a role.\n", "tags": [ "RBAC" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List users (deprecated path)", "description": "Returns a paginated list of users with optional search.\n", "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": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create user (deprecated path)", "description": "Manually creates a new user in the organization.\n", "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": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get user (deprecated path)", "description": "Returns a single Enterprise user.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MessageResponse" }, { "type": "object", "properties": { "redivision_job_ids": { "type": "array", "items": { "type": "string" }, "description": "One queued job per equal-split governance project the user belonged to, since removing them enlarges every remaining member's slice of every cap. Present only when such projects were affected. Progress is reported on the `redivision_progress` WebSocket channel under each id." } } } ] } } } }, "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `UserProvisioning:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get user's teams (deprecated path)", "description": "Returns the list of teams a user belongs to, including the membership source.\n", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Users:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get user by email (deprecated path)", "description": "Returns a single Enterprise user resolved by URL-encoded email address.\n", "tags": [ "Users" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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_units": { "type": "array", "description": "Business units the user belongs to. Membership is many-to-many and belongs to the user, so this is the authoritative list; manage it under `/api/governance/business-units/{business_unit_id}/users`.\n", "items": { "type": "object", "description": "A business unit the user belongs to.", "properties": { "id": { "type": "string", "description": "Business unit ID" }, "name": { "type": "string", "description": "Business unit name" } } } }, "access_profiles": { "type": "array", "description": "Every access profile the user holds, one per assignment source. All of them are enforced — their budgets, rate limits, and provider access combine.\n", "items": { "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" } } } }, "access_profile": { "type": "object", "nullable": true, "description": "Deprecated. A single-value summary of the highest-precedence profile (`attribute_mapping` > `role_default` > `manual`), kept for clients written before a user could hold several. It grants nothing on its own — read `access_profiles` instead.\n", "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", "x-mint": { "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams` instead.\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n", "metadata": { "tag": "Removing soon" } }, "summary": "List teams (deprecated path)", "description": "Returns a list of all teams.\n", "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": [] }, { "BasicAuth": [] } ], "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 }, "post": { "operationId": "createTeamLegacy", "x-mint": { "content": "\n This path is deprecated and will be removed in the following major release.\n Use `/api/governance/teams` instead.\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n", "metadata": { "tag": "Removing soon" } }, "summary": "Create team (deprecated path)", "description": "Creates a new team.\n", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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 } }, "/api/teams/{team_id}": { "get": { "operationId": "getTeamLegacy", "x-mint": { "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**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n", "metadata": { "tag": "Removing soon" } }, "summary": "Get team (deprecated path)", "description": "Returns a specific team by ID.\n", "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": [] }, { "BasicAuth": [] } ], "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 }, "put": { "operationId": "updateTeamLegacy", "x-mint": { "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**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n", "metadata": { "tag": "Removing soon" } }, "summary": "Update team (deprecated path)", "description": "Updates an existing team.\n", "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": [] }, { "BasicAuth": [] } ], "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 }, "delete": { "operationId": "deleteTeamLegacy", "x-mint": { "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**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n", "metadata": { "tag": "Removing soon" } }, "summary": "Delete team (deprecated path)", "description": "Deletes a team.\n", "tags": [ "Governance" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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 } }, "/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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List team members (deprecated path)", "description": "Returns all members of a team with their user details and membership source.\n", "tags": [ "Teams" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Add team member (deprecated path)", "description": "Adds a user to a team. Both the team and user must exist.\n", "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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Teams:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Remove team member (deprecated path)", "description": "Removes a user from a team.\n", "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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List access profiles (deprecated path)", "description": "Returns access profiles visible to the caller.\n", "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": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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" }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "oneOf": [ { "type": "string", "description": "Rotation interval as a day count (\"30d\") or a Go duration (\"12h\", \"720h\"). Must resolve to between 1h and 365d. \"\" disables rotation.", "pattern": "^$|^[0-9]+d$|^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$", "example": "30d" }, { "type": "integer", "format": "int64", "description": "Rotation interval in nanoseconds. 0 disables rotation; otherwise between 1h (3600000000000) and 365d (31536000000000000).", "oneOf": [ { "const": 0 }, { "minimum": 3600000000000, "maximum": 31536000000000000 } ], "example": 2592000000000000 } ], "description": "Schedule automatic rotation of the profile's managed virtual keys. Accepts a day count (\"30d\"), a Go duration (\"12h\"), or integer nanoseconds. Between 1h and 365d; omit, \"\" or 0 to leave it off.", "example": "30d" }, "next_rotation_at": { "type": "string", "format": "date-time", "description": "Optional first rotation time; must be in the future and requires auto_rotation_interval. Defaults to now + interval." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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 }, "allow_all_providers": { "type": "boolean", "nullable": true, "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false, provider-wide access is disabled and access is deny-by-default via provider_configs. Omit to leave unchanged." }, "auto_rotation_interval": { "oneOf": [ { "type": "string", "description": "Rotation interval as a day count (\"30d\") or a Go duration (\"12h\", \"720h\"). Must resolve to between 1h and 365d. \"\" disables rotation.", "pattern": "^$|^[0-9]+d$|^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$", "example": "30d" }, { "type": "integer", "format": "int64", "description": "Rotation interval in nanoseconds. 0 disables rotation; otherwise between 1h (3600000000000) and 365d (31536000000000000).", "oneOf": [ { "const": 0 }, { "minimum": 3600000000000, "maximum": 31536000000000000 } ], "example": 2592000000000000 }, { "type": "null" } ], "description": "Replace the rotation schedule (\"30d\", \"12h\" or nanoseconds); \"\" or 0 turns it off. Omit to leave the schedule unchanged." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Override the next rotation time (must be in the future). null clears it, which is only valid when the interval is off. Omit to keep the existing schedule; a changed interval re-anchors it to now + interval." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Activate access profile (deprecated path)", "description": "Sets the profile active. Idempotent.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Deactivate access profile (deprecated path)", "description": "Sets the profile inactive. Idempotent. User copies are preserved; the profile is hidden from selection menus.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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.\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": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, grants access to every provider, including ones without a provider_configs entry and providers added later. A listed provider keeps its own model allow/blacklist, budgets, rate limits, and key selection; an unlisted provider gets all models, all keys, and no per-provider limits. When false (default), access is deny-by-default via provider_configs." }, "auto_rotation_interval": { "type": "integer", "format": "int64", "description": "Interval between automatic rotations of the profile's managed virtual keys, in nanoseconds. 0 means automatic rotation is off." }, "next_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled rotation is due. Absent while automatic rotation is off." }, "last_rotation_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the last scheduled rotation run finished." }, "virtual_mcps": { "type": "array", "items": { "type": "object", "description": "A Virtual MCP granted to the profile. Assignments are a set, so a repeat collapses rather than doubling.", "anyOf": [ { "required": [ "virtual_mcp_name" ] }, { "required": [ "virtual_mcp_id" ] } ], "properties": { "virtual_mcp_name": { "type": "string", "description": "Name of the Virtual MCP. Resolved to the stored Virtual MCP on save; a name that matches none is refused." }, "virtual_mcp_id": { "type": "integer", "format": "uint", "minimum": 1, "description": "Virtual MCP ID, as an alternative to virtual_mcp_name. Wins when both are set." } } } }, "mcp_configs": { "type": "array", "items": { "type": "object", "description": "The tools of one MCP client the profile may execute.", "required": [ "mcp_client_id" ], "properties": { "mcp_client_id": { "type": "string", "description": "MCP client ID or name. A name is resolved to the stored client id on save; a ref matching no client is kept as given." }, "tools_to_execute": { "type": "array", "items": { "type": "string" }, "description": "[\"*\"] allows every tool including ones added later, [] allows none, and a named list allows only those tools." } } } }, "mcp_tool_groups": { "deprecated": true, "description": "DEPRECATED: use virtual_mcps.", "type": "array", "items": { "type": "object", "deprecated": true, "description": "DEPRECATED: use AccessProfileVirtualMCPLink (virtual_mcps).", "required": [ "tool_group_id" ], "properties": { "tool_group_id": { "type": "integer", "format": "uint" } } } }, "mcp_servers": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "type": "array", "items": { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } }, "mcp_tool_overrides": { "deprecated": true, "description": "DEPRECATED: use mcp_configs. Folded in on save.", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List virtual keys available to a user (deprecated path)", "description": "Returns every virtual key assigned to the user, independent of access profiles, so\ndirectly-assigned standalone keys are visible alongside profile-issued ones.\n", "tags": [ "Users", "Virtual Keys" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "User virtual keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "virtual_keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "is_access_profile_managed": { "type": "boolean", "description": "True when an access profile governs this key, in which case its policy is edit-locked and changed by editing and propagating the profile.\n" } } } } } } } } } }, "x-bifrost-successor": "/api/governance/users/{user_id}/virtual-keys", "x-bifrost-removal": "following-major-release", "deprecated": true }, "post": { "operationId": "addUserVirtualKeyLegacy", "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualKeys:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Mint an extra virtual key for a user (deprecated path)", "description": "Issues an additional virtual key for the user.\n\nVirtual keys are scoped to the **user**, not to any one access profile: what a request may\ndo with the key is read from whichever of the user's active profiles grants it, and each of\nthose profiles is a separate routing candidate the request may be served by. The user must\ntherefore hold at least one access profile — the request returns 404 otherwise — but the key\nis not tied to the profile that happened to be current when it was minted, and it survives\nthat profile being detached as long as the user still holds another.\n", "tags": [ "Users", "Virtual Keys" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "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 has no access profiles" }, "409": { "description": "A virtual key with this name already exists" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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\n`budget_id` must be a budget on the user's own copy of the profile, not on the\nshared 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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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", "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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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.\n", "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": [] }, { "BasicAuth": [] } ], "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", "deprecated": true, "x-bifrost-successor": "/api/governance/users/{user_id}/virtual-keys", "x-bifrost-removal": "following-major-release", "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\n **Deprecated.** Use [`POST /api/governance/users/{user_id}/virtual-keys`](/api-reference/governance/mint-an-extra-virtual-key-for-a-user)\n instead. This path still works and behaves identically, but will be removed in a future major release.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Add an extra virtual key under a user's access profile (deprecated) (deprecated path)", "description": "Issues an additional virtual key for the user. \n\nVirtual keys are scoped to the **user**, not to one access profile: what a request may do with\nthe key is resolved at request time from whichever of the user's active profiles grant it. So\n`profile_id` is ignored — the key minted is the same whichever profile is named, and it is not\nbound to that profile or removed with it. The user must hold at least one access profile.\n", "tags": [ "Access Profiles" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "description": "Ignored. Kept so the path shape stays valid for existing clients; keys are user-scoped, so any value produces the same result.\n", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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." } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "User has no access profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "409": { "description": "A virtual key with this name already exists" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AccessProfiles:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get audit log by ID", "description": "Retrieves a single audit log event by its unique ID.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the audit log event.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get audit log by ID (deprecated path)", "description": "Retrieves a single audit log event by its unique ID.\n", "tags": [ "Audit Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the audit log event.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `AuditLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualMCPs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualMCPs:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualMCPs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get MCP Tool Group by ID", "tags": [ "MCP Tool Groups" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualMCPs:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `VirtualMCPs:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete MCP Tool Group", "description": "Deletes the group; attachments are removed automatically.\n", "tags": [ "MCP Tool Groups" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `CircuitBreaker:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List circuit breaker policies", "description": "Returns all circuit breaker policies defined in this workspace.\n", "tags": [ "Circuit Breaker" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `CircuitBreaker:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `CircuitBreaker:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `CircuitBreaker:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `CircuitBreaker:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List routing rules", "description": "Returns a list of all routing rules configured for intelligent request routing across providers.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "tags": [ "Routing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingRuleRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get routing rule", "description": "Returns a specific routing rule by ID.\n", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update routing rule", "description": "Updates an existing routing rule's configuration.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete routing rule", "description": "Deletes a routing rule.\n", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get complexity analyzer config", "description": "Returns the full complexity analyzer runtime config, including the semantic embedding configuration, the llm fallback classifier configuration, and per-tier reference phrase lists. Returns built-in defaults if none have been configured.\n", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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": [ "keywords" ], "allOf": [ { "if": { "properties": { "session": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] } }, "required": [ "session" ] }, "then": { "required": [ "semantic" ] } }, { "if": { "properties": { "semantic": { "properties": { "fallback": { "const": "llm" } }, "required": [ "fallback" ] } }, "required": [ "semantic" ] }, "then": { "required": [ "llm" ] } } ], "properties": { "tier_boundaries": { "type": "object", "deprecated": true, "description": "Deprecated score thresholds for the retired lexical complexity classifier.\nThis block is optional and ignored by semantic classification, but remains\naccepted for backward compatibility. When supplied, values must satisfy\n0 < simple_medium < medium_complex < 1.\n", "additionalProperties": false, "required": [ "simple_medium", "medium_complex" ], "properties": { "simple_medium": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between SIMPLE and MEDIUM tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between MEDIUM and COMPLEX tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Reference phrases for semantic complexity classification, one list per tier.\nEach request is embedded and takes the tier of its nearest phrase. Entries\nshould be whole example prompts rather than individual keywords. Each phrase\nis limited to 2000 characters, the normalized lists may contain at most 750\nphrases combined, and the same phrase cannot appear in two tiers. The field\nnames predate semantic classification and are kept for backward compatibility.\n", "additionalProperties": false, "required": [ "simple_keywords", "medium_keywords", "complex_keywords" ], "properties": { "simple_keywords": { "type": "array", "description": "Reference phrases for the SIMPLE tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "medium_keywords": { "type": "array", "description": "Reference phrases for the MEDIUM tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "complex_keywords": { "type": "array", "description": "Reference phrases for the COMPLEX tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 } } }, "semantic": { "type": "object", "description": "Embedding configuration for semantic complexity classification. When absent,\nno complexity tier is published and rules referencing complexity_tier fall\nthrough. The provider must have an enabled key.\n", "additionalProperties": false, "required": [ "provider", "embedding_model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used for embedding calls (must have an enabled key)" }, "embedding_model": { "type": "string", "minLength": 1, "description": "Embedding model, e.g. text-embedding-3-small" }, "timeout": { "description": "Ceiling on the inline embedding call. Accepts a duration string (\"1.5s\") or milliseconds as a number. Default 1.5s; exceeding it publishes no tier for that request.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "min_similarity": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Similarity floor for the nearest reference phrase; below it no tier is published. 0 (default) accepts the nearest eligible match. Compared against the vector store backend's own similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis, certainty for Weaviate)." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of recent user messages joined oldest-first into the embedded text. 1 (default) embeds only the latest message. System prompts and assistant replies are never embedded." }, "count_toward_budgets": { "type": "boolean", "description": "Whether embedding usage counts toward virtual-key budgets (default false)" }, "vector_store": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where reference-phrase embeddings live. `embedded` (default) uses the\nbuilt-in in-memory store, so phrases are re-embedded on every restart.\n`vector_store` uses the top-level `vector_store` when one is configured\nand falls back to the embedded store otherwise.\n" }, "fallback": { "type": "string", "enum": [ "none", "llm" ], "description": "What answers when semantic classification produces no tier (a match\nbelow `min_similarity`, a timeout, or an unfinished warmup). `none`\n(the default) records the request as skipped. `llm` asks the chat\nmodel configured in the analyzer's `llm` block, which is required\nwhen this is set.\n" } } }, "llm": { "type": "object", "description": "Chat-completion (LLM) fallback classifier settings. The block is inert\nunless `semantic.fallback` selects `llm`; the classifier runs only after\nsemantic classification produces no tier. Tier names (SIMPLE, MEDIUM,\nCOMPLEX) and the response format are fixed: the gateway always appends a\nnon-editable reinforcement stating them.\n", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used to run the classification chat completion (must have an enabled key)" }, "model": { "type": "string", "minLength": 1, "description": "Chat model asked to name the tier. Every fallback classification waits on one completion from this model, so pick a small, fast one." }, "timeout": { "description": "Per-request classification timeout. Accepts a duration string (\"2s\") or milliseconds as a number. Default 4s. On timeout no complexity tier is published and the request is recorded as skipped.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "prompt": { "type": "string", "maxLength": 4000, "description": "Replaces the shipped classification guidance (max 4000 characters); empty means the shipped guidance is used. The tier-name and response-format reinforcement is appended by the gateway either way and cannot be edited." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many of the most recent user messages are given to the classifier, oldest first (default 1, the latest message only). Only user turns count; system prompts and assistant replies are never sent." }, "count_toward_budgets": { "type": "boolean", "description": "Whether classification completion cost counts toward virtual-key budgets (record-only, never enforced; default false)" } } }, "session": { "type": "object", "description": "Session-aware complexity routing. When enabled and a request carries a supported session identity, Bifrost retains the highest tier observed across normally sequential turns for 24 hours of inactivity. Overlapping requests for the same session are best-effort and resolve by last writer wins.", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable monotonic session tier retention. Requires semantic complexity classification; default is false." } } } } } } } }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update complexity analyzer config", "description": "Replaces the full complexity analyzer runtime config and hot-reloads the routing plugin. Changing the embedding configuration or reference phrases triggers a background re-warm of the classifier; unchanged phrases are not re-embedded. Setting semantic.fallback to llm requires the llm block to be present.\n", "tags": [ "Routing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "keywords" ], "allOf": [ { "if": { "properties": { "session": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] } }, "required": [ "session" ] }, "then": { "required": [ "semantic" ] } }, { "if": { "properties": { "semantic": { "properties": { "fallback": { "const": "llm" } }, "required": [ "fallback" ] } }, "required": [ "semantic" ] }, "then": { "required": [ "llm" ] } } ], "properties": { "tier_boundaries": { "type": "object", "deprecated": true, "description": "Deprecated score thresholds for the retired lexical complexity classifier.\nThis block is optional and ignored by semantic classification, but remains\naccepted for backward compatibility. When supplied, values must satisfy\n0 < simple_medium < medium_complex < 1.\n", "additionalProperties": false, "required": [ "simple_medium", "medium_complex" ], "properties": { "simple_medium": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between SIMPLE and MEDIUM tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between MEDIUM and COMPLEX tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Reference phrases for semantic complexity classification, one list per tier.\nEach request is embedded and takes the tier of its nearest phrase. Entries\nshould be whole example prompts rather than individual keywords. Each phrase\nis limited to 2000 characters, the normalized lists may contain at most 750\nphrases combined, and the same phrase cannot appear in two tiers. The field\nnames predate semantic classification and are kept for backward compatibility.\n", "additionalProperties": false, "required": [ "simple_keywords", "medium_keywords", "complex_keywords" ], "properties": { "simple_keywords": { "type": "array", "description": "Reference phrases for the SIMPLE tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "medium_keywords": { "type": "array", "description": "Reference phrases for the MEDIUM tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "complex_keywords": { "type": "array", "description": "Reference phrases for the COMPLEX tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 } } }, "semantic": { "type": "object", "description": "Embedding configuration for semantic complexity classification. When absent,\nno complexity tier is published and rules referencing complexity_tier fall\nthrough. The provider must have an enabled key.\n", "additionalProperties": false, "required": [ "provider", "embedding_model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used for embedding calls (must have an enabled key)" }, "embedding_model": { "type": "string", "minLength": 1, "description": "Embedding model, e.g. text-embedding-3-small" }, "timeout": { "description": "Ceiling on the inline embedding call. Accepts a duration string (\"1.5s\") or milliseconds as a number. Default 1.5s; exceeding it publishes no tier for that request.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "min_similarity": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Similarity floor for the nearest reference phrase; below it no tier is published. 0 (default) accepts the nearest eligible match. Compared against the vector store backend's own similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis, certainty for Weaviate)." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of recent user messages joined oldest-first into the embedded text. 1 (default) embeds only the latest message. System prompts and assistant replies are never embedded." }, "count_toward_budgets": { "type": "boolean", "description": "Whether embedding usage counts toward virtual-key budgets (default false)" }, "vector_store": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where reference-phrase embeddings live. `embedded` (default) uses the\nbuilt-in in-memory store, so phrases are re-embedded on every restart.\n`vector_store` uses the top-level `vector_store` when one is configured\nand falls back to the embedded store otherwise.\n" }, "fallback": { "type": "string", "enum": [ "none", "llm" ], "description": "What answers when semantic classification produces no tier (a match\nbelow `min_similarity`, a timeout, or an unfinished warmup). `none`\n(the default) records the request as skipped. `llm` asks the chat\nmodel configured in the analyzer's `llm` block, which is required\nwhen this is set.\n" } } }, "llm": { "type": "object", "description": "Chat-completion (LLM) fallback classifier settings. The block is inert\nunless `semantic.fallback` selects `llm`; the classifier runs only after\nsemantic classification produces no tier. Tier names (SIMPLE, MEDIUM,\nCOMPLEX) and the response format are fixed: the gateway always appends a\nnon-editable reinforcement stating them.\n", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used to run the classification chat completion (must have an enabled key)" }, "model": { "type": "string", "minLength": 1, "description": "Chat model asked to name the tier. Every fallback classification waits on one completion from this model, so pick a small, fast one." }, "timeout": { "description": "Per-request classification timeout. Accepts a duration string (\"2s\") or milliseconds as a number. Default 4s. On timeout no complexity tier is published and the request is recorded as skipped.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "prompt": { "type": "string", "maxLength": 4000, "description": "Replaces the shipped classification guidance (max 4000 characters); empty means the shipped guidance is used. The tier-name and response-format reinforcement is appended by the gateway either way and cannot be edited." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many of the most recent user messages are given to the classifier, oldest first (default 1, the latest message only). Only user turns count; system prompts and assistant replies are never sent." }, "count_toward_budgets": { "type": "boolean", "description": "Whether classification completion cost counts toward virtual-key budgets (record-only, never enforced; default false)" } } }, "session": { "type": "object", "description": "Session-aware complexity routing. When enabled and a request carries a supported session identity, Bifrost retains the highest tier observed across normally sequential turns for 24 hours of inactivity. Overlapping requests for the same session are best-effort and resolve by last writer wins.", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable monotonic session tier retention. Requires semantic complexity classification; default is false." } } } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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": [ "keywords" ], "allOf": [ { "if": { "properties": { "session": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] } }, "required": [ "session" ] }, "then": { "required": [ "semantic" ] } }, { "if": { "properties": { "semantic": { "properties": { "fallback": { "const": "llm" } }, "required": [ "fallback" ] } }, "required": [ "semantic" ] }, "then": { "required": [ "llm" ] } } ], "properties": { "tier_boundaries": { "type": "object", "deprecated": true, "description": "Deprecated score thresholds for the retired lexical complexity classifier.\nThis block is optional and ignored by semantic classification, but remains\naccepted for backward compatibility. When supplied, values must satisfy\n0 < simple_medium < medium_complex < 1.\n", "additionalProperties": false, "required": [ "simple_medium", "medium_complex" ], "properties": { "simple_medium": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between SIMPLE and MEDIUM tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between MEDIUM and COMPLEX tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Reference phrases for semantic complexity classification, one list per tier.\nEach request is embedded and takes the tier of its nearest phrase. Entries\nshould be whole example prompts rather than individual keywords. Each phrase\nis limited to 2000 characters, the normalized lists may contain at most 750\nphrases combined, and the same phrase cannot appear in two tiers. The field\nnames predate semantic classification and are kept for backward compatibility.\n", "additionalProperties": false, "required": [ "simple_keywords", "medium_keywords", "complex_keywords" ], "properties": { "simple_keywords": { "type": "array", "description": "Reference phrases for the SIMPLE tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "medium_keywords": { "type": "array", "description": "Reference phrases for the MEDIUM tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "complex_keywords": { "type": "array", "description": "Reference phrases for the COMPLEX tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 } } }, "semantic": { "type": "object", "description": "Embedding configuration for semantic complexity classification. When absent,\nno complexity tier is published and rules referencing complexity_tier fall\nthrough. The provider must have an enabled key.\n", "additionalProperties": false, "required": [ "provider", "embedding_model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used for embedding calls (must have an enabled key)" }, "embedding_model": { "type": "string", "minLength": 1, "description": "Embedding model, e.g. text-embedding-3-small" }, "timeout": { "description": "Ceiling on the inline embedding call. Accepts a duration string (\"1.5s\") or milliseconds as a number. Default 1.5s; exceeding it publishes no tier for that request.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "min_similarity": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Similarity floor for the nearest reference phrase; below it no tier is published. 0 (default) accepts the nearest eligible match. Compared against the vector store backend's own similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis, certainty for Weaviate)." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of recent user messages joined oldest-first into the embedded text. 1 (default) embeds only the latest message. System prompts and assistant replies are never embedded." }, "count_toward_budgets": { "type": "boolean", "description": "Whether embedding usage counts toward virtual-key budgets (default false)" }, "vector_store": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where reference-phrase embeddings live. `embedded` (default) uses the\nbuilt-in in-memory store, so phrases are re-embedded on every restart.\n`vector_store` uses the top-level `vector_store` when one is configured\nand falls back to the embedded store otherwise.\n" }, "fallback": { "type": "string", "enum": [ "none", "llm" ], "description": "What answers when semantic classification produces no tier (a match\nbelow `min_similarity`, a timeout, or an unfinished warmup). `none`\n(the default) records the request as skipped. `llm` asks the chat\nmodel configured in the analyzer's `llm` block, which is required\nwhen this is set.\n" } } }, "llm": { "type": "object", "description": "Chat-completion (LLM) fallback classifier settings. The block is inert\nunless `semantic.fallback` selects `llm`; the classifier runs only after\nsemantic classification produces no tier. Tier names (SIMPLE, MEDIUM,\nCOMPLEX) and the response format are fixed: the gateway always appends a\nnon-editable reinforcement stating them.\n", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used to run the classification chat completion (must have an enabled key)" }, "model": { "type": "string", "minLength": 1, "description": "Chat model asked to name the tier. Every fallback classification waits on one completion from this model, so pick a small, fast one." }, "timeout": { "description": "Per-request classification timeout. Accepts a duration string (\"2s\") or milliseconds as a number. Default 4s. On timeout no complexity tier is published and the request is recorded as skipped.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "prompt": { "type": "string", "maxLength": 4000, "description": "Replaces the shipped classification guidance (max 4000 characters); empty means the shipped guidance is used. The tier-name and response-format reinforcement is appended by the gateway either way and cannot be edited." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many of the most recent user messages are given to the classifier, oldest first (default 1, the latest message only). Only user turns count; system prompts and assistant replies are never sent." }, "count_toward_budgets": { "type": "boolean", "description": "Whether classification completion cost counts toward virtual-key budgets (record-only, never enforced; default false)" } } }, "session": { "type": "object", "description": "Session-aware complexity routing. When enabled and a request carries a supported session identity, Bifrost retains the highest tier observed across normally sequential turns for 24 hours of inactivity. Overlapping requests for the same session are best-effort and resolve by last writer wins.", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable monotonic session tier retention. Requires semantic complexity classification; default is false." } } } } } } } }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Reset complexity analyzer config", "description": "Restores the built-in reference phrase lists and hot-reloads the routing plugin. The saved embedding provider, model, storage configuration, and llm fallback configuration are preserved.\n", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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": [ "keywords" ], "allOf": [ { "if": { "properties": { "session": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] } }, "required": [ "session" ] }, "then": { "required": [ "semantic" ] } }, { "if": { "properties": { "semantic": { "properties": { "fallback": { "const": "llm" } }, "required": [ "fallback" ] } }, "required": [ "semantic" ] }, "then": { "required": [ "llm" ] } } ], "properties": { "tier_boundaries": { "type": "object", "deprecated": true, "description": "Deprecated score thresholds for the retired lexical complexity classifier.\nThis block is optional and ignored by semantic classification, but remains\naccepted for backward compatibility. When supplied, values must satisfy\n0 < simple_medium < medium_complex < 1.\n", "additionalProperties": false, "required": [ "simple_medium", "medium_complex" ], "properties": { "simple_medium": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between SIMPLE and MEDIUM tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between MEDIUM and COMPLEX tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Reference phrases for semantic complexity classification, one list per tier.\nEach request is embedded and takes the tier of its nearest phrase. Entries\nshould be whole example prompts rather than individual keywords. Each phrase\nis limited to 2000 characters, the normalized lists may contain at most 750\nphrases combined, and the same phrase cannot appear in two tiers. The field\nnames predate semantic classification and are kept for backward compatibility.\n", "additionalProperties": false, "required": [ "simple_keywords", "medium_keywords", "complex_keywords" ], "properties": { "simple_keywords": { "type": "array", "description": "Reference phrases for the SIMPLE tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "medium_keywords": { "type": "array", "description": "Reference phrases for the MEDIUM tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "complex_keywords": { "type": "array", "description": "Reference phrases for the COMPLEX tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 } } }, "semantic": { "type": "object", "description": "Embedding configuration for semantic complexity classification. When absent,\nno complexity tier is published and rules referencing complexity_tier fall\nthrough. The provider must have an enabled key.\n", "additionalProperties": false, "required": [ "provider", "embedding_model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used for embedding calls (must have an enabled key)" }, "embedding_model": { "type": "string", "minLength": 1, "description": "Embedding model, e.g. text-embedding-3-small" }, "timeout": { "description": "Ceiling on the inline embedding call. Accepts a duration string (\"1.5s\") or milliseconds as a number. Default 1.5s; exceeding it publishes no tier for that request.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "min_similarity": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Similarity floor for the nearest reference phrase; below it no tier is published. 0 (default) accepts the nearest eligible match. Compared against the vector store backend's own similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis, certainty for Weaviate)." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of recent user messages joined oldest-first into the embedded text. 1 (default) embeds only the latest message. System prompts and assistant replies are never embedded." }, "count_toward_budgets": { "type": "boolean", "description": "Whether embedding usage counts toward virtual-key budgets (default false)" }, "vector_store": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where reference-phrase embeddings live. `embedded` (default) uses the\nbuilt-in in-memory store, so phrases are re-embedded on every restart.\n`vector_store` uses the top-level `vector_store` when one is configured\nand falls back to the embedded store otherwise.\n" }, "fallback": { "type": "string", "enum": [ "none", "llm" ], "description": "What answers when semantic classification produces no tier (a match\nbelow `min_similarity`, a timeout, or an unfinished warmup). `none`\n(the default) records the request as skipped. `llm` asks the chat\nmodel configured in the analyzer's `llm` block, which is required\nwhen this is set.\n" } } }, "llm": { "type": "object", "description": "Chat-completion (LLM) fallback classifier settings. The block is inert\nunless `semantic.fallback` selects `llm`; the classifier runs only after\nsemantic classification produces no tier. Tier names (SIMPLE, MEDIUM,\nCOMPLEX) and the response format are fixed: the gateway always appends a\nnon-editable reinforcement stating them.\n", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used to run the classification chat completion (must have an enabled key)" }, "model": { "type": "string", "minLength": 1, "description": "Chat model asked to name the tier. Every fallback classification waits on one completion from this model, so pick a small, fast one." }, "timeout": { "description": "Per-request classification timeout. Accepts a duration string (\"2s\") or milliseconds as a number. Default 4s. On timeout no complexity tier is published and the request is recorded as skipped.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "prompt": { "type": "string", "maxLength": 4000, "description": "Replaces the shipped classification guidance (max 4000 characters); empty means the shipped guidance is used. The tier-name and response-format reinforcement is appended by the gateway either way and cannot be edited." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many of the most recent user messages are given to the classifier, oldest first (default 1, the latest message only). Only user turns count; system prompts and assistant replies are never sent." }, "count_toward_budgets": { "type": "boolean", "description": "Whether classification completion cost counts toward virtual-key budgets (record-only, never enforced; default false)" } } }, "session": { "type": "object", "description": "Session-aware complexity routing. When enabled and a request carries a supported session identity, Bifrost retains the highest tier observed across normally sequential turns for 24 hours of inactivity. Overlapping requests for the same session are best-effort and resolve by last writer wins.", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable monotonic session tier retention. Requires semantic complexity classification; default is false." } } } } } } } }, "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-status": { "get": { "operationId": "getComplexityAnalyzerStatus", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get complexity classifier status", "description": "Returns the runtime status of the semantic complexity classifier (disabled, warming, ready, or failed), including warmup progress and whether a previous generation is still serving. When the llm fallback block is configured, also returns its readiness and the shipped default classification prompt.\n", "tags": [ "Routing" ], "responses": { "200": { "description": "Complexity classifier status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Runtime status of the semantic complexity classifier and, when configured, the LLM fallback classifier. Never contains phrases, embeddings, or provider secrets.", "properties": { "state": { "type": "string", "enum": [ "disabled", "warming", "ready", "failed" ], "description": "disabled = no embedding configuration; warming = reference phrases are being embedded; ready = serving the current configuration; failed = the desired configuration failed to warm" }, "loaded": { "type": "integer", "description": "Reference phrases embedded so far in the current warmup" }, "total": { "type": "integer", "description": "Total reference phrases to embed in the current warmup" }, "serving_previous": { "type": "boolean", "description": "When true with state=failed, the previous generation is still serving while the new one failed to warm" }, "failure_reason": { "type": "string", "enum": [ "authentication", "model_unavailable", "rate_limited", "timeout", "provider_unavailable", "vector_store_unavailable", "invalid_response", "unknown" ], "description": "Category of a warmup failure when state=failed. Provider and backend error bodies stay in server logs; this bounded vocabulary is what status clients receive." }, "error": { "type": "string", "description": "Warmup failure detail when state=failed" }, "cached_phrases": { "type": "integer", "description": "How many phrase vectors the gateway currently holds in process for the configured provider and model. The cache is in-process only, since vectors cannot be read back out of a vector store, so a restart empties it while the saved phrases look unchanged. Zero means the next save re-embeds every phrase regardless of what changed." }, "storage_mode": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where exemplar vectors are actually kept, which is not always what was configured. semantic.vector_store=vector_store degrades to embedded whenever no top-level vector store is configured, so this reports what is in force rather than what was asked for. Absent until a store has been resolved." }, "namespace": { "type": "string", "description": "The fingerprinted namespace the serving generation queries, for example BifrostComplexityRouter_. The backend holds no phrase text, so this is the only handle on the records the classifier owns in a shared vector store. Absent while nothing is serving." }, "llm": { "type": "object", "description": "Always present in the response. state is disabled when no llm block is configured.", "properties": { "state": { "type": "string", "enum": [ "disabled", "ready" ], "description": "disabled = no llm configuration; ready = the llm block is configured. The classifier has no warmup, so it is ready as soon as it is saved." } } }, "llm_default_prompt": { "type": "string", "description": "The shipped classification guidance, served so a configuration client can seed its prompt editor and offer a reset without holding a copy that drifts from the gateway's. Always present in the response, regardless of whether an llm block is configured." } } } } } }, "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-status/retry": { "post": { "operationId": "retryComplexityAnalyzerWarmup", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Retry failed complexity classifier warmup", "description": "Restarts the saved semantic classifier warmup only when its current state is failed. The retry runs asynchronously and does not change the saved configuration.\n", "tags": [ "Routing" ], "responses": { "202": { "description": "Semantic warmup retry accepted", "content": { "application/json": { "schema": { "type": "object", "description": "Runtime status of the semantic complexity classifier and, when configured, the LLM fallback classifier. Never contains phrases, embeddings, or provider secrets.", "properties": { "state": { "type": "string", "enum": [ "disabled", "warming", "ready", "failed" ], "description": "disabled = no embedding configuration; warming = reference phrases are being embedded; ready = serving the current configuration; failed = the desired configuration failed to warm" }, "loaded": { "type": "integer", "description": "Reference phrases embedded so far in the current warmup" }, "total": { "type": "integer", "description": "Total reference phrases to embed in the current warmup" }, "serving_previous": { "type": "boolean", "description": "When true with state=failed, the previous generation is still serving while the new one failed to warm" }, "failure_reason": { "type": "string", "enum": [ "authentication", "model_unavailable", "rate_limited", "timeout", "provider_unavailable", "vector_store_unavailable", "invalid_response", "unknown" ], "description": "Category of a warmup failure when state=failed. Provider and backend error bodies stay in server logs; this bounded vocabulary is what status clients receive." }, "error": { "type": "string", "description": "Warmup failure detail when state=failed" }, "cached_phrases": { "type": "integer", "description": "How many phrase vectors the gateway currently holds in process for the configured provider and model. The cache is in-process only, since vectors cannot be read back out of a vector store, so a restart empties it while the saved phrases look unchanged. Zero means the next save re-embeds every phrase regardless of what changed." }, "storage_mode": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where exemplar vectors are actually kept, which is not always what was configured. semantic.vector_store=vector_store degrades to embedded whenever no top-level vector store is configured, so this reports what is in force rather than what was asked for. Absent until a store has been resolved." }, "namespace": { "type": "string", "description": "The fingerprinted namespace the serving generation queries, for example BifrostComplexityRouter_. The backend holds no phrase text, so this is the only handle on the records the classifier owns in a shared vector store. Absent while nothing is serving." }, "llm": { "type": "object", "description": "Always present in the response. state is disabled when no llm block is configured.", "properties": { "state": { "type": "string", "enum": [ "disabled", "ready" ], "description": "disabled = no llm configuration; ready = the llm block is configured. The classifier has no warmup, so it is ready as soon as it is saved." } } }, "llm_default_prompt": { "type": "string", "description": "The shipped classification guidance, served so a configuration client can seed its prompt editor and offer a reset without holding a copy that drifts from the gateway's. Always present in the response, regardless of whether an llm block is configured." } } } } } }, "409": { "description": "The semantic classifier is not currently failed", "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-generations": { "get": { "operationId": "listComplexityGenerations", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List complexity classifier generations", "description": "Lists the exemplar generations held in the vector store for semantic complexity routing, flagging the one currently serving. Every configuration change mints a new fingerprinted generation; a node-local store reclaims the previous one automatically, but on a shared external store retired generations are kept because another replica may still be serving them. The store holds no phrase text, so this listing is the only way to identify what has accumulated.\n", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Generations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "The exemplar generations the vector store currently holds for semantic complexity routing.", "properties": { "generations": { "type": "array", "description": "One entry per fingerprinted namespace, ordered by name. Empty when no vector store has been resolved.", "items": { "type": "object", "properties": { "namespace": { "type": "string", "description": "The fingerprinted namespace holding the generation.", "example": "BifrostComplexityRouter_943f4d9a1b0502568b4dc4911c81cfa8c8b3fb3eb71311e732c95b18003cfdb5" }, "active": { "type": "boolean", "description": "Whether classification currently queries this generation. Exactly one is active while the classifier is ready; every other entry is retired and unreachable by any request." } } } } } } } } }, "503": { "description": "The vector store could not be enumerated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/routing/complexity-analyzer-generations/{namespace}": { "delete": { "operationId": "deleteComplexityGeneration", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete a retired complexity generation", "description": "Removes one retired exemplar generation and the vectors it holds. The serving generation is refused, as are namespaces outside the classifier's own naming scheme, so this cannot drop an unrelated collection sharing the same backend. Deleting a generation that is already gone succeeds.\n", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] } ], "parameters": [ { "name": "namespace", "in": "path", "required": true, "description": "The fingerprinted namespace to remove, as returned by the generations listing.", "schema": { "type": "string", "example": "BifrostComplexityRouter_943f4d9a1b0502568b4dc4911c81cfa8c8b3fb3eb71311e732c95b18003cfdb5" } } ], "responses": { "200": { "description": "Generation deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "deleted" }, "namespace": { "type": "string" } } } } } }, "400": { "description": "The namespace is not a complexity routing generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "409": { "description": "The generation is currently serving classification requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "503": { "description": "The vector store could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/governance/routing-rules": { "get": { "operationId": "listRoutingRulesLegacy", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "tags": [ "Routing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingRuleRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `RoutingRules:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "tags": [ "Routing" ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Routing rule ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "deprecated": true, "summary": "Get complexity analyzer config (deprecated path)", "description": "Returns the full complexity analyzer runtime config, including the semantic embedding configuration, the llm fallback classifier configuration, and per-tier reference phrase 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.\n", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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": [ "keywords" ], "allOf": [ { "if": { "properties": { "session": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] } }, "required": [ "session" ] }, "then": { "required": [ "semantic" ] } }, { "if": { "properties": { "semantic": { "properties": { "fallback": { "const": "llm" } }, "required": [ "fallback" ] } }, "required": [ "semantic" ] }, "then": { "required": [ "llm" ] } } ], "properties": { "tier_boundaries": { "type": "object", "deprecated": true, "description": "Deprecated score thresholds for the retired lexical complexity classifier.\nThis block is optional and ignored by semantic classification, but remains\naccepted for backward compatibility. When supplied, values must satisfy\n0 < simple_medium < medium_complex < 1.\n", "additionalProperties": false, "required": [ "simple_medium", "medium_complex" ], "properties": { "simple_medium": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between SIMPLE and MEDIUM tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between MEDIUM and COMPLEX tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Reference phrases for semantic complexity classification, one list per tier.\nEach request is embedded and takes the tier of its nearest phrase. Entries\nshould be whole example prompts rather than individual keywords. Each phrase\nis limited to 2000 characters, the normalized lists may contain at most 750\nphrases combined, and the same phrase cannot appear in two tiers. The field\nnames predate semantic classification and are kept for backward compatibility.\n", "additionalProperties": false, "required": [ "simple_keywords", "medium_keywords", "complex_keywords" ], "properties": { "simple_keywords": { "type": "array", "description": "Reference phrases for the SIMPLE tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "medium_keywords": { "type": "array", "description": "Reference phrases for the MEDIUM tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "complex_keywords": { "type": "array", "description": "Reference phrases for the COMPLEX tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 } } }, "semantic": { "type": "object", "description": "Embedding configuration for semantic complexity classification. When absent,\nno complexity tier is published and rules referencing complexity_tier fall\nthrough. The provider must have an enabled key.\n", "additionalProperties": false, "required": [ "provider", "embedding_model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used for embedding calls (must have an enabled key)" }, "embedding_model": { "type": "string", "minLength": 1, "description": "Embedding model, e.g. text-embedding-3-small" }, "timeout": { "description": "Ceiling on the inline embedding call. Accepts a duration string (\"1.5s\") or milliseconds as a number. Default 1.5s; exceeding it publishes no tier for that request.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "min_similarity": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Similarity floor for the nearest reference phrase; below it no tier is published. 0 (default) accepts the nearest eligible match. Compared against the vector store backend's own similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis, certainty for Weaviate)." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of recent user messages joined oldest-first into the embedded text. 1 (default) embeds only the latest message. System prompts and assistant replies are never embedded." }, "count_toward_budgets": { "type": "boolean", "description": "Whether embedding usage counts toward virtual-key budgets (default false)" }, "vector_store": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where reference-phrase embeddings live. `embedded` (default) uses the\nbuilt-in in-memory store, so phrases are re-embedded on every restart.\n`vector_store` uses the top-level `vector_store` when one is configured\nand falls back to the embedded store otherwise.\n" }, "fallback": { "type": "string", "enum": [ "none", "llm" ], "description": "What answers when semantic classification produces no tier (a match\nbelow `min_similarity`, a timeout, or an unfinished warmup). `none`\n(the default) records the request as skipped. `llm` asks the chat\nmodel configured in the analyzer's `llm` block, which is required\nwhen this is set.\n" } } }, "llm": { "type": "object", "description": "Chat-completion (LLM) fallback classifier settings. The block is inert\nunless `semantic.fallback` selects `llm`; the classifier runs only after\nsemantic classification produces no tier. Tier names (SIMPLE, MEDIUM,\nCOMPLEX) and the response format are fixed: the gateway always appends a\nnon-editable reinforcement stating them.\n", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used to run the classification chat completion (must have an enabled key)" }, "model": { "type": "string", "minLength": 1, "description": "Chat model asked to name the tier. Every fallback classification waits on one completion from this model, so pick a small, fast one." }, "timeout": { "description": "Per-request classification timeout. Accepts a duration string (\"2s\") or milliseconds as a number. Default 4s. On timeout no complexity tier is published and the request is recorded as skipped.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "prompt": { "type": "string", "maxLength": 4000, "description": "Replaces the shipped classification guidance (max 4000 characters); empty means the shipped guidance is used. The tier-name and response-format reinforcement is appended by the gateway either way and cannot be edited." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many of the most recent user messages are given to the classifier, oldest first (default 1, the latest message only). Only user turns count; system prompts and assistant replies are never sent." }, "count_toward_budgets": { "type": "boolean", "description": "Whether classification completion cost counts toward virtual-key budgets (record-only, never enforced; default false)" } } }, "session": { "type": "object", "description": "Session-aware complexity routing. When enabled and a request carries a supported session identity, Bifrost retains the highest tier observed across normally sequential turns for 24 hours of inactivity. Overlapping requests for the same session are best-effort and resolve by last writer wins.", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable monotonic session tier retention. Requires semantic complexity classification; default is false." } } } } } } } }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "deprecated": true, "summary": "Update complexity analyzer config (deprecated path)", "description": "Replaces the full complexity analyzer runtime config and hot-reloads the routing plugin. Changing the embedding configuration or reference phrases triggers a background re-warm of the classifier; unchanged phrases are not re-embedded. Setting semantic.fallback to llm requires the llm block to be present. Deprecated, use /api/routing/complexity-analyzer-config instead. This path is kept for backwards compatibility and behaves identically.\n", "tags": [ "Routing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Full runtime configuration for complexity routing analysis.", "additionalProperties": false, "required": [ "keywords" ], "allOf": [ { "if": { "properties": { "session": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] } }, "required": [ "session" ] }, "then": { "required": [ "semantic" ] } }, { "if": { "properties": { "semantic": { "properties": { "fallback": { "const": "llm" } }, "required": [ "fallback" ] } }, "required": [ "semantic" ] }, "then": { "required": [ "llm" ] } } ], "properties": { "tier_boundaries": { "type": "object", "deprecated": true, "description": "Deprecated score thresholds for the retired lexical complexity classifier.\nThis block is optional and ignored by semantic classification, but remains\naccepted for backward compatibility. When supplied, values must satisfy\n0 < simple_medium < medium_complex < 1.\n", "additionalProperties": false, "required": [ "simple_medium", "medium_complex" ], "properties": { "simple_medium": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between SIMPLE and MEDIUM tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between MEDIUM and COMPLEX tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Reference phrases for semantic complexity classification, one list per tier.\nEach request is embedded and takes the tier of its nearest phrase. Entries\nshould be whole example prompts rather than individual keywords. Each phrase\nis limited to 2000 characters, the normalized lists may contain at most 750\nphrases combined, and the same phrase cannot appear in two tiers. The field\nnames predate semantic classification and are kept for backward compatibility.\n", "additionalProperties": false, "required": [ "simple_keywords", "medium_keywords", "complex_keywords" ], "properties": { "simple_keywords": { "type": "array", "description": "Reference phrases for the SIMPLE tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "medium_keywords": { "type": "array", "description": "Reference phrases for the MEDIUM tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "complex_keywords": { "type": "array", "description": "Reference phrases for the COMPLEX tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 } } }, "semantic": { "type": "object", "description": "Embedding configuration for semantic complexity classification. When absent,\nno complexity tier is published and rules referencing complexity_tier fall\nthrough. The provider must have an enabled key.\n", "additionalProperties": false, "required": [ "provider", "embedding_model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used for embedding calls (must have an enabled key)" }, "embedding_model": { "type": "string", "minLength": 1, "description": "Embedding model, e.g. text-embedding-3-small" }, "timeout": { "description": "Ceiling on the inline embedding call. Accepts a duration string (\"1.5s\") or milliseconds as a number. Default 1.5s; exceeding it publishes no tier for that request.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "min_similarity": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Similarity floor for the nearest reference phrase; below it no tier is published. 0 (default) accepts the nearest eligible match. Compared against the vector store backend's own similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis, certainty for Weaviate)." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of recent user messages joined oldest-first into the embedded text. 1 (default) embeds only the latest message. System prompts and assistant replies are never embedded." }, "count_toward_budgets": { "type": "boolean", "description": "Whether embedding usage counts toward virtual-key budgets (default false)" }, "vector_store": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where reference-phrase embeddings live. `embedded` (default) uses the\nbuilt-in in-memory store, so phrases are re-embedded on every restart.\n`vector_store` uses the top-level `vector_store` when one is configured\nand falls back to the embedded store otherwise.\n" }, "fallback": { "type": "string", "enum": [ "none", "llm" ], "description": "What answers when semantic classification produces no tier (a match\nbelow `min_similarity`, a timeout, or an unfinished warmup). `none`\n(the default) records the request as skipped. `llm` asks the chat\nmodel configured in the analyzer's `llm` block, which is required\nwhen this is set.\n" } } }, "llm": { "type": "object", "description": "Chat-completion (LLM) fallback classifier settings. The block is inert\nunless `semantic.fallback` selects `llm`; the classifier runs only after\nsemantic classification produces no tier. Tier names (SIMPLE, MEDIUM,\nCOMPLEX) and the response format are fixed: the gateway always appends a\nnon-editable reinforcement stating them.\n", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used to run the classification chat completion (must have an enabled key)" }, "model": { "type": "string", "minLength": 1, "description": "Chat model asked to name the tier. Every fallback classification waits on one completion from this model, so pick a small, fast one." }, "timeout": { "description": "Per-request classification timeout. Accepts a duration string (\"2s\") or milliseconds as a number. Default 4s. On timeout no complexity tier is published and the request is recorded as skipped.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "prompt": { "type": "string", "maxLength": 4000, "description": "Replaces the shipped classification guidance (max 4000 characters); empty means the shipped guidance is used. The tier-name and response-format reinforcement is appended by the gateway either way and cannot be edited." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many of the most recent user messages are given to the classifier, oldest first (default 1, the latest message only). Only user turns count; system prompts and assistant replies are never sent." }, "count_toward_budgets": { "type": "boolean", "description": "Whether classification completion cost counts toward virtual-key budgets (record-only, never enforced; default false)" } } }, "session": { "type": "object", "description": "Session-aware complexity routing. When enabled and a request carries a supported session identity, Bifrost retains the highest tier observed across normally sequential turns for 24 hours of inactivity. Overlapping requests for the same session are best-effort and resolve by last writer wins.", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable monotonic session tier retention. Requires semantic complexity classification; default is false." } } } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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": [ "keywords" ], "allOf": [ { "if": { "properties": { "session": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] } }, "required": [ "session" ] }, "then": { "required": [ "semantic" ] } }, { "if": { "properties": { "semantic": { "properties": { "fallback": { "const": "llm" } }, "required": [ "fallback" ] } }, "required": [ "semantic" ] }, "then": { "required": [ "llm" ] } } ], "properties": { "tier_boundaries": { "type": "object", "deprecated": true, "description": "Deprecated score thresholds for the retired lexical complexity classifier.\nThis block is optional and ignored by semantic classification, but remains\naccepted for backward compatibility. When supplied, values must satisfy\n0 < simple_medium < medium_complex < 1.\n", "additionalProperties": false, "required": [ "simple_medium", "medium_complex" ], "properties": { "simple_medium": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between SIMPLE and MEDIUM tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between MEDIUM and COMPLEX tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Reference phrases for semantic complexity classification, one list per tier.\nEach request is embedded and takes the tier of its nearest phrase. Entries\nshould be whole example prompts rather than individual keywords. Each phrase\nis limited to 2000 characters, the normalized lists may contain at most 750\nphrases combined, and the same phrase cannot appear in two tiers. The field\nnames predate semantic classification and are kept for backward compatibility.\n", "additionalProperties": false, "required": [ "simple_keywords", "medium_keywords", "complex_keywords" ], "properties": { "simple_keywords": { "type": "array", "description": "Reference phrases for the SIMPLE tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "medium_keywords": { "type": "array", "description": "Reference phrases for the MEDIUM tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "complex_keywords": { "type": "array", "description": "Reference phrases for the COMPLEX tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 } } }, "semantic": { "type": "object", "description": "Embedding configuration for semantic complexity classification. When absent,\nno complexity tier is published and rules referencing complexity_tier fall\nthrough. The provider must have an enabled key.\n", "additionalProperties": false, "required": [ "provider", "embedding_model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used for embedding calls (must have an enabled key)" }, "embedding_model": { "type": "string", "minLength": 1, "description": "Embedding model, e.g. text-embedding-3-small" }, "timeout": { "description": "Ceiling on the inline embedding call. Accepts a duration string (\"1.5s\") or milliseconds as a number. Default 1.5s; exceeding it publishes no tier for that request.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "min_similarity": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Similarity floor for the nearest reference phrase; below it no tier is published. 0 (default) accepts the nearest eligible match. Compared against the vector store backend's own similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis, certainty for Weaviate)." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of recent user messages joined oldest-first into the embedded text. 1 (default) embeds only the latest message. System prompts and assistant replies are never embedded." }, "count_toward_budgets": { "type": "boolean", "description": "Whether embedding usage counts toward virtual-key budgets (default false)" }, "vector_store": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where reference-phrase embeddings live. `embedded` (default) uses the\nbuilt-in in-memory store, so phrases are re-embedded on every restart.\n`vector_store` uses the top-level `vector_store` when one is configured\nand falls back to the embedded store otherwise.\n" }, "fallback": { "type": "string", "enum": [ "none", "llm" ], "description": "What answers when semantic classification produces no tier (a match\nbelow `min_similarity`, a timeout, or an unfinished warmup). `none`\n(the default) records the request as skipped. `llm` asks the chat\nmodel configured in the analyzer's `llm` block, which is required\nwhen this is set.\n" } } }, "llm": { "type": "object", "description": "Chat-completion (LLM) fallback classifier settings. The block is inert\nunless `semantic.fallback` selects `llm`; the classifier runs only after\nsemantic classification produces no tier. Tier names (SIMPLE, MEDIUM,\nCOMPLEX) and the response format are fixed: the gateway always appends a\nnon-editable reinforcement stating them.\n", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used to run the classification chat completion (must have an enabled key)" }, "model": { "type": "string", "minLength": 1, "description": "Chat model asked to name the tier. Every fallback classification waits on one completion from this model, so pick a small, fast one." }, "timeout": { "description": "Per-request classification timeout. Accepts a duration string (\"2s\") or milliseconds as a number. Default 4s. On timeout no complexity tier is published and the request is recorded as skipped.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "prompt": { "type": "string", "maxLength": 4000, "description": "Replaces the shipped classification guidance (max 4000 characters); empty means the shipped guidance is used. The tier-name and response-format reinforcement is appended by the gateway either way and cannot be edited." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many of the most recent user messages are given to the classifier, oldest first (default 1, the latest message only). Only user turns count; system prompts and assistant replies are never sent." }, "count_toward_budgets": { "type": "boolean", "description": "Whether classification completion cost counts toward virtual-key budgets (record-only, never enforced; default false)" } } }, "session": { "type": "object", "description": "Session-aware complexity routing. When enabled and a request carries a supported session identity, Bifrost retains the highest tier observed across normally sequential turns for 24 hours of inactivity. Overlapping requests for the same session are best-effort and resolve by last writer wins.", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable monotonic session tier retention. Requires semantic complexity classification; default is false." } } } } } } } }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Governance:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "deprecated": true, "summary": "Reset complexity analyzer config (deprecated path)", "description": "Restores the built-in reference phrase lists and hot-reloads the routing plugin. The saved embedding provider, model, storage configuration, and llm fallback configuration are preserved. Deprecated, use /api/routing/complexity-analyzer-config/reset instead. This path is kept for backwards compatibility and behaves identically.\n", "tags": [ "Routing" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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": [ "keywords" ], "allOf": [ { "if": { "properties": { "session": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] } }, "required": [ "session" ] }, "then": { "required": [ "semantic" ] } }, { "if": { "properties": { "semantic": { "properties": { "fallback": { "const": "llm" } }, "required": [ "fallback" ] } }, "required": [ "semantic" ] }, "then": { "required": [ "llm" ] } } ], "properties": { "tier_boundaries": { "type": "object", "deprecated": true, "description": "Deprecated score thresholds for the retired lexical complexity classifier.\nThis block is optional and ignored by semantic classification, but remains\naccepted for backward compatibility. When supplied, values must satisfy\n0 < simple_medium < medium_complex < 1.\n", "additionalProperties": false, "required": [ "simple_medium", "medium_complex" ], "properties": { "simple_medium": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between SIMPLE and MEDIUM tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "medium_complex": { "type": "number", "deprecated": true, "description": "Deprecated score boundary between MEDIUM and COMPLEX tiers (ignored by semantic classification)", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } }, "keywords": { "type": "object", "description": "Reference phrases for semantic complexity classification, one list per tier.\nEach request is embedded and takes the tier of its nearest phrase. Entries\nshould be whole example prompts rather than individual keywords. Each phrase\nis limited to 2000 characters, the normalized lists may contain at most 750\nphrases combined, and the same phrase cannot appear in two tiers. The field\nnames predate semantic classification and are kept for backward compatibility.\n", "additionalProperties": false, "required": [ "simple_keywords", "medium_keywords", "complex_keywords" ], "properties": { "simple_keywords": { "type": "array", "description": "Reference phrases for the SIMPLE tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "medium_keywords": { "type": "array", "description": "Reference phrases for the MEDIUM tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 }, "complex_keywords": { "type": "array", "description": "Reference phrases for the COMPLEX tier (50 built-in defaults)", "items": { "type": "string", "maxLength": 2000 }, "minItems": 1 } } }, "semantic": { "type": "object", "description": "Embedding configuration for semantic complexity classification. When absent,\nno complexity tier is published and rules referencing complexity_tier fall\nthrough. The provider must have an enabled key.\n", "additionalProperties": false, "required": [ "provider", "embedding_model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used for embedding calls (must have an enabled key)" }, "embedding_model": { "type": "string", "minLength": 1, "description": "Embedding model, e.g. text-embedding-3-small" }, "timeout": { "description": "Ceiling on the inline embedding call. Accepts a duration string (\"1.5s\") or milliseconds as a number. Default 1.5s; exceeding it publishes no tier for that request.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "min_similarity": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Similarity floor for the nearest reference phrase; below it no tier is published. 0 (default) accepts the nearest eligible match. Compared against the vector store backend's own similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis, certainty for Weaviate)." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of recent user messages joined oldest-first into the embedded text. 1 (default) embeds only the latest message. System prompts and assistant replies are never embedded." }, "count_toward_budgets": { "type": "boolean", "description": "Whether embedding usage counts toward virtual-key budgets (default false)" }, "vector_store": { "type": "string", "enum": [ "embedded", "vector_store" ], "description": "Where reference-phrase embeddings live. `embedded` (default) uses the\nbuilt-in in-memory store, so phrases are re-embedded on every restart.\n`vector_store` uses the top-level `vector_store` when one is configured\nand falls back to the embedded store otherwise.\n" }, "fallback": { "type": "string", "enum": [ "none", "llm" ], "description": "What answers when semantic classification produces no tier (a match\nbelow `min_similarity`, a timeout, or an unfinished warmup). `none`\n(the default) records the request as skipped. `llm` asks the chat\nmodel configured in the analyzer's `llm` block, which is required\nwhen this is set.\n" } } }, "llm": { "type": "object", "description": "Chat-completion (LLM) fallback classifier settings. The block is inert\nunless `semantic.fallback` selects `llm`; the classifier runs only after\nsemantic classification produces no tier. Tier names (SIMPLE, MEDIUM,\nCOMPLEX) and the response format are fixed: the gateway always appends a\nnon-editable reinforcement stating them.\n", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Provider used to run the classification chat completion (must have an enabled key)" }, "model": { "type": "string", "minLength": 1, "description": "Chat model asked to name the tier. Every fallback classification waits on one completion from this model, so pick a small, fast one." }, "timeout": { "description": "Per-request classification timeout. Accepts a duration string (\"2s\") or milliseconds as a number. Default 4s. On timeout no complexity tier is published and the request is recorded as skipped.", "oneOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)$" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "prompt": { "type": "string", "maxLength": 4000, "description": "Replaces the shipped classification guidance (max 4000 characters); empty means the shipped guidance is used. The tier-name and response-format reinforcement is appended by the gateway either way and cannot be edited." }, "message_history_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many of the most recent user messages are given to the classifier, oldest first (default 1, the latest message only). Only user turns count; system prompts and assistant replies are never sent." }, "count_toward_budgets": { "type": "boolean", "description": "Whether classification completion cost counts toward virtual-key budgets (record-only, never enforced; default false)" } } }, "session": { "type": "object", "description": "Session-aware complexity routing. When enabled and a request carries a supported session identity, Bifrost retains the highest tier observed across normally sequential turns for 24 hours of inactivity. Overlapping requests for the same session are best-effort and resolve by last writer wins.", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable monotonic session tier retention. Requires semantic complexity classification; default is false." } } } } } } } }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "tool_call_names", "in": "query", "description": "Comma-separated list of function names. Matches requests whose response called any of them, using the persisted tool_call_names metadata on the log row. Names are recorded even when content logging is disabled and stay on the row in hybrid storage mode; the call arguments are not.", "schema": { "type": "string" } }, { "name": "complexity_tiers", "in": "query", "description": "Comma-separated list of routing complexity tiers to filter by (SIMPLE, MEDIUM, COMPLEX, or the legacy REASONING tier recorded on historical rows before it was merged into COMPLEX)", "schema": { "type": "string" } }, { "name": "complexity_mechanisms", "in": "query", "description": "Comma-separated list of complexity decision mechanisms to filter by (semantic, llm, session, or skipped)", "schema": { "type": "string" } }, { "name": "session_id", "in": "query", "description": "Exact Bifrost session ID used for key stickiness and request correlation", "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": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete logs", "description": "Deletes logs by their IDs.\n", "tags": [ "Logging" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteLogsRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get a single log entry", "description": "Retrieves a single log entry by its ID.\n", "tags": [ "Logging" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Log entry ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get aggregate totals for a session", "description": "Returns aggregate request count, token usage, cost, and duration for a single session.\n", "tags": [ "Logging" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "Parent request ID identifying the session", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get log statistics", "description": "Returns statistics for logs matching the specified filters.\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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "tool_call_names", "in": "query", "description": "Comma-separated list of function names. Matches requests whose response called any of them, using the persisted tool_call_names metadata on the log row. Names are recorded even when content logging is disabled and stay on the row in hybrid storage mode; the call arguments are not.", "schema": { "type": "string" } }, { "name": "complexity_tiers", "in": "query", "description": "Comma-separated list of routing complexity tiers to filter by (SIMPLE, MEDIUM, COMPLEX, or the legacy REASONING tier recorded on historical rows before it was merged into COMPLEX)", "schema": { "type": "string" } }, { "name": "complexity_mechanisms", "in": "query", "description": "Comma-separated list of complexity decision mechanisms to filter by (semantic, llm, session, or skipped)", "schema": { "type": "string" } }, { "name": "session_id", "in": "query", "description": "Exact Bifrost session ID used for key stickiness and request correlation", "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": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } }, { "name": "compare_to_previous", "in": "query", "description": "When true, also return the same statistics for the immediately preceding window of equal length, so callers can render change-vs-previous-period. Requires a bounded window (start_time and end_time, or period); an unbounded all-time filter has no preceding window, and the response then omits `previous` with `has_previous_period` false. A failure to compute the previous period degrades to `has_previous_period` false rather than failing the request.", "schema": { "type": "boolean", "default": false } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogStatsResponse" } } } }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "tool_call_names", "in": "query", "description": "Comma-separated list of function names. Matches requests whose response called any of them, using the persisted tool_call_names metadata on the log row. Names are recorded even when content logging is disabled and stay on the row in hybrid storage mode; the call arguments are not.", "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": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get token usage histogram", "description": "Returns time-bucketed token usage (prompt, completion, total).\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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get cost histogram", "description": "Returns time-bucketed cost data with model breakdown.\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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get model usage histogram", "description": "Returns time-bucketed model usage with success/error breakdown.\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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get latency histogram", "description": "Returns time-bucketed latency percentiles (avg, p90, p95, p99).\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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get cost histogram by provider", "description": "Returns time-bucketed cost data with provider breakdown.\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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get token histogram by provider", "description": "Returns time-bucketed token usage with provider breakdown.\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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get latency histogram by provider", "description": "Returns time-bucketed latency percentiles with provider breakdown.\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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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`,\n`project_id`, `app`, `user_agent`). The dimension is supplied via the\nrequired `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", "project_id", "app", "user_agent" ] } }, { "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "project_id", "app", "user_agent" ] }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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", "project_id", "app", "user_agent" ] } }, { "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "project_id", "app", "user_agent" ] }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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", "project_id", "app", "user_agent" ] } }, { "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "project_id", "app", "user_agent" ] }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get dropped requests count", "description": "Returns the number of dropped requests.\n", "tags": [ "Logging" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get available filter data", "description": "Returns the distinct values each filter dimension offers, drawn from the logs of roughly the last month.", "tags": [ "Logging" ], "parameters": [ { "name": "dimensions", "in": "query", "description": "Comma-separated dimensions to return. One or more of `models`, `aliases`, `selected_keys`, `virtual_keys`, `routing_rules`, `routing_engines`, `stop_reasons`, `tool_call_names`, `apps`, `user_agents`, `teams`, `customers`, `users`, `business_units`, `projects`, `metadata_keys`. Unrecognised values are ignored, and asking for none returns every dimension.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Free-text search within the requested dimensions. Passing it bypasses the response cache.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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)" }, "tool_call_names": { "type": "array", "items": { "type": "string" }, "description": "Function names that logged responses have called, for the tool calls filter. Read from the persisted tool_call_names metadata, so it stays available when message content is not logged or is offloaded in hybrid storage mode." }, "projects": { "type": "array", "items": { "type": "object", "description": "An id and its display name, as offered by a filter dimension.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "description": "Governance projects that appear in the logs, for the `projects` dimension. Only projects whose rows carry a name are listed." } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } } } }, "/api/logs/histogram/throughput": { "get": { "operationId": "getLogsThroughputHistogram", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get throughput histogram", "description": "Returns time-bucketed token-generation throughput in tokens per second. The bucket size is derived from the requested window.", "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": "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed token-generation throughput.", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "One time bucket of token-generation throughput.", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "tokens_per_second": { "type": "number" }, "total_completion_tokens": { "type": "integer", "format": "int64" }, "total_requests": { "type": "integer", "format": "int64" } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64", "description": "Bucket width, derived from the requested window." } } } } } }, "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/throughput/by-provider": { "get": { "operationId": "getLogsProviderThroughputHistogram", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get throughput histogram by provider", "description": "Returns time-bucketed tokens per second with a per-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": "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "content_search", "in": "query", "description": "Search in request/response content", "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Time-bucketed throughput with a per-provider breakdown.", "properties": { "buckets": { "type": "array", "items": { "type": "object", "description": "One time bucket of throughput, broken down by provider.", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "by_provider": { "type": "object", "description": "Keyed by provider name.", "additionalProperties": { "type": "object", "description": "Throughput figures for one provider within a bucket.", "properties": { "tokens_per_second": { "type": "number" }, "total_completion_tokens": { "type": "integer", "format": "int64" }, "total_requests": { "type": "integer", "format": "int64" } } } } } } }, "bucket_size_seconds": { "type": "integer", "format": "int64" }, "providers": { "type": "array", "items": { "type": "string" }, "description": "Providers present across the returned buckets." } } } } } }, "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/rankings": { "get": { "operationId": "getModelRankings", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "tool_call_names", "in": "query", "description": "Comma-separated list of function names. Matches requests whose response called any of them, using the persisted tool_call_names metadata on the log row. Names are recorded even when content logging is disabled and stay on the row in hybrid storage mode; the call arguments are not.", "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": "session_id", "in": "query", "description": "Exact Bifrost session ID used for key stickiness and request correlation", "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": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "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/rankings/by-dimension": { "get": { "operationId": "getDimensionRankings", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get rankings by governance dimension", "description": "Returns the entities of one governance dimension ranked by spend, tokens\nand request volume, with trend percentages versus the previous comparable\nperiod. Requests carrying no value for the dimension are reported under an\n`Unassigned` entry rather than dropped, so the rows reconcile with real\ntraffic.\n\nNote that the accepted `dimension` values differ from the ones the\n`/by-dimension` histogram endpoints take: rankings use `project` where the\nhistograms use `project_id`.\n", "tags": [ "Logging" ], "parameters": [ { "name": "dimension", "in": "query", "required": true, "description": "The governance dimension to rank by.", "schema": { "type": "string", "description": "Entity used to group dimension rankings", "enum": [ "team", "customer", "business_unit", "project", "user", "virtual_key", "app", "user_agent" ] } }, { "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "tool_call_names", "in": "query", "description": "Comma-separated list of function names. Matches requests whose response called any of them, using the persisted tool_call_names metadata on the log row. Names are recorded even when content logging is disabled and stay on the row in hybrid storage mode; the call arguments are not.", "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": "session_id", "in": "query", "description": "Exact Bifrost session ID used for key stickiness and request correlation", "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": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "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": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Dimension rankings retrieved successfully", "content": { "application/json": { "schema": { "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", "project", "user", "virtual_key", "app", "user_agent" ] }, "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" } } } } } }, "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/rankings/users": { "get": { "operationId": "getUserRankings", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Dashboard:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get user usage rankings", "description": "Returns users ranked by spend, tokens and request volume, with trend percentages versus the previous comparable period. Only requests that resolved to a user are counted.", "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": "routing_rule_ids", "in": "query", "description": "Comma-separated list of routing rule 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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "period", "in": "query", "description": "Relative time period filter", "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": "User rankings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "rankings": { "type": "array", "items": { "type": "object", "description": "One user's usage totals, with its trend.", "properties": { "user_id": { "type": "string" }, "total_requests": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" }, "total_cost": { "type": "number" }, "trend": { "type": "object", "description": "Change versus the previous comparable period.", "properties": { "has_previous_period": { "type": "boolean", "description": "False when there is no earlier window to compare against." }, "requests_trend": { "type": "number" }, "tokens_trend": { "type": "number" }, "cost_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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": "project_ids", "in": "query", "description": "Comma-separated list of project 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": "tool_call_names", "in": "query", "description": "Comma-separated list of function names. Matches requests whose response called any of them, using the persisted tool_call_names metadata on the log row. Names are recorded even when content logging is disabled and stay on the row in hybrid storage mode; the call arguments are not.", "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": "session_id", "in": "query", "description": "Exact Bifrost session ID used for key stickiness and request correlation", "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": "request_id", "in": "query", "description": "Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.", "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": [] }, { "BasicAuth": [] } ], "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`, `project`, `app`, `user_agent`); each\nvalue 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", "project", "user", "virtual_key", "app", "user_agent" ] }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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\nRecalculation updates the cost fields on matching log records only. It does not\nretroactively debit, credit, or otherwise adjust governance budget usage. Governance\nbudgets retain the usage recorded when each request was originally processed.\n", "tags": [ "Logging" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecalculateCostRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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/logs/recalculate-cost/cancel": { "post": { "operationId": "cancelRecalculateCost", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Logs:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Cancel log cost recalculation", "description": "Cancels the recalculation job selected by `id`, or the current in-flight recalculation\nwhen `id` is omitted. Cancellation stops further batches; cost updates already committed\nto log records are retained and are not rolled back. Logs that the job has not processed\nremain unchanged.\n\nThe response uses the same job-status shape as the status endpoint and includes the\npartial progress recorded at the time of the response. The worker may still be unwinding,\nso poll the status endpoint with the returned `id` to obtain its final counters. If the\nselected job has already reached a terminal state, the endpoint returns it unchanged.\n", "tags": [ "Logging" ], "parameters": [ { "name": "id", "in": "query", "description": "Optional recalculation job ID. Omit to cancel the current in-flight recalculation.", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Recalculation cancellation accepted, or the selected job was already terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecalculateCostResponse" } } } }, "400": { "description": "The supplied job ID belongs to a different background-job type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementErrorResponse" } } } }, "404": { "description": "The requested job was not found, or there is no in-flight recalculation to cancel", "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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" }, "project_id": { "type": "string", "nullable": true, "description": "The governance project the tool call was scoped to, or null when it named none. Recorded on the row, but the MCP log queries cannot filter on it." }, "project_name": { "type": "string", "nullable": true, "description": "The project's name as it stood when the tool call was served." }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPLogs:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete MCP tool logs", "description": "Deletes MCP tool logs by their IDs.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get MCP tool log by ID", "description": "Retrieves a single MCP tool execution log by ID, including hydrated object-storage payloads when configured.\n", "tags": [ "Logging" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP tool log ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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" }, "project_id": { "type": "string", "nullable": true, "description": "The governance project the tool call was scoped to, or null when it named none. Recorded on the row, but the MCP log queries cannot filter on it." }, "project_name": { "type": "string", "nullable": true, "description": "The project's name as it stood when the tool call was served." }, "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get MCP tool log statistics", "description": "Returns statistics for MCP tool logs matching the specified filters.\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", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get available MCP log filter data", "description": "Returns all unique filter data from MCP tool logs (tool names, server labels).\n", "tags": [ "Logging" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get MCP tool call volume histogram", "description": "Returns time-bucketed MCP tool call volume with success/error breakdown.\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" } }, { "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get MCP cost histogram", "description": "Returns time-bucketed MCP tool call cost data.\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" } }, { "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `MCPLogs:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get top MCP tools by call count", "description": "Returns the top 10 MCP tools by call count, with cost totals.\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" } }, { "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List folders", "description": "Returns all prompt folders.\n", "tags": [ "Prompt Repository" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create folder", "description": "Creates a new prompt folder.\n", "tags": [ "Prompt Repository" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get folder", "description": "Returns a folder by ID.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update folder", "description": "Updates a folder's name or description.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete folder", "description": "Deletes a folder and cascades to contained prompts.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List prompts", "description": "Returns all prompts, optionally filtered by folder.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "folder_id", "in": "query", "description": "Filter by folder ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create prompt", "description": "Creates a new prompt.\n", "tags": [ "Prompt Repository" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "folder_id": { "type": "string" } } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get prompt", "description": "Returns a prompt by ID with its latest version.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update prompt", "description": "Updates a prompt's name or folder.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete prompt", "description": "Deletes a prompt and all its versions and sessions.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List prompt versions", "description": "Returns all versions for a prompt.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Prompt ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create prompt version", "description": "Creates a new version for a prompt.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get prompt version", "description": "Returns a specific version by ID.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Version ID", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete prompt version", "description": "Deletes a specific version.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Version ID", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List prompt sessions", "description": "Returns all sessions for a prompt.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Prompt ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create prompt session", "description": "Creates a new playground session for a prompt.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get prompt session", "description": "Returns a specific session by ID.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Session ID", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update prompt session", "description": "Updates a session's messages, model params, etc.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete prompt session", "description": "Deletes a specific session.\n", "tags": [ "Prompt Repository" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Session ID", "schema": { "type": "integer" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Rename prompt session", "description": "Renames a session.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `PromptRepository:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Commit session as version", "description": "Commits the current session state as a new prompt version.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "tags": [ "Skills" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadSkillFileRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get all-skills version", "description": "Returns the current version of the synthetic `bifrost-all-skills` marketplace plugin.\n", "tags": [ "Skills" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Bump all-skills version", "description": "Manually bumps the synthetic `bifrost-all-skills` plugin version as an escape hatch for marketplace refreshes.\n", "tags": [ "Skills" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BumpAllSkillsVersionRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List skills", "description": "Returns a paginated list of skills from the Skills Repository.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create skill", "description": "Creates a new skill and immediately serves its first immutable version.\n", "tags": [ "Skills" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillRequest" } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get skill", "description": "Returns a skill by ID. Pass `version` to inspect a historical version snapshot.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update skill", "description": "Creates a new immutable skill version. Set `serve` to false to save the version without switching the served version.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete skill", "description": "Deletes a skill and all of its versions.\n", "tags": [ "Skills" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill ID", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List skill versions", "description": "Returns immutable version snapshots for a skill.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `SkillsRepository:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Shift served skill version", "description": "Changes the served version for a skill without deleting newer versions.\n", "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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.\n", "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get Codex skills marketplace JSON", "description": "Public Codex marketplace JSON for inspecting the skills and plugin sources exposed by Bifrost.\n", "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Download all skills as ZIP", "description": "Public ZIP download containing every currently served skill.\n", "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Download skill as ZIP", "description": "Public ZIP download containing a single currently served skill.\n", "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Public endpoint - no authentication required |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Download skill file", "description": "Public raw file download from the currently served version of a skill.\n", "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Clear cache by cache key", "description": "Clears a cache entry by its direct cache key.\n", "tags": [ "Cache" ], "parameters": [ { "name": "cacheKey", "in": "path", "required": true, "description": "Cache key to clear", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "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\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Settings:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\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": [] }, { "BasicAuth": [] } ], "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Any authenticated caller - exempt from RBAC |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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\nEvery message is an envelope with a `type` discriminator. Two carry\ngovernance-project state:\n\n- `store_update` names the resources that changed, so a client holding a\n cached list can refetch it. A project create, edit, delete or member\n change sends `{\"type\": \"store_update\", \"tags\": [\"Projects\"]}`.\n- `redivision_progress` reports an equal-split project recalculating\n every member's share of every cap. Its `operation_id` matches the\n `redivision_job_id` returned by the project and member routes, and by\n a user deletion, so a client can follow the job it started.\n\nThe message shapes are documented as `StoreUpdateMessage` and\n`RedivisionProgressMessage`; they arrive over the socket rather than as\nan HTTP response body.\n", "tags": [ "Infrastructure" ], "parameters": [ { "name": "ticket", "in": "query", "required": false, "description": "Single-use WebSocket ticket from `POST /api/session/ws-ticket`. Use this when an\n`Authorization` header cannot be set (browser WebSocket clients).\n", "schema": { "type": "string" } } ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] }, { "SessionCookieAuth": [] } ], "responses": { "101": { "description": "WebSocket upgrade successful", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Names the resources that changed, so a client holding a cached list knows to refetch it. Project creates, edits, deletes and member changes all send `tags: [\"Projects\"]`.", "properties": { "type": { "type": "string", "const": "store_update" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Resource names, matching the dashboard's cache tags, for example `Projects`, `VirtualKeys`, `Providers`, `MCPClients`.", "example": [ "Projects" ] } } }, { "type": "object", "description": "Envelope carrying a redivision progress update.", "properties": { "type": { "type": "string", "const": "redivision_progress" }, "data": { "type": "object", "description": "Progress of one equal-split project recalculating every member's share of every cap it holds.", "properties": { "operation_id": { "type": "string", "description": "The job this reports on, matching the `redivision_job_id` returned by the project and member routes, or one of the `redivision_job_ids` returned by a user deletion." }, "project_id": { "type": "string" }, "phase": { "type": "string", "enum": [ "redividing", "completed", "error" ] }, "total": { "type": "integer", "description": "Members in the roster when the job started." }, "processed": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "message": { "type": "string", "description": "A closing summary on `completed`, or the failure text on `error`. A project deleted between queueing and running completes without work." } } } } } ], "description": "One of the server-pushed message envelopes. Listed here because the spec has nowhere else to describe a socket payload." } } } } } } }, "/mcp": { "post": { "operationId": "mcpServerMessage", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Not RBAC-gated - authorized by the credential below |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] }, "get": { "operationId": "mcpServerSSE", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Not RBAC-gated - authorized by the credential below |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "VirtualKeyAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/metrics": { "get": { "operationId": "getMetrics", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Metrics:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Prometheus metrics", "description": "Returns Prometheus-formatted metrics for monitoring.\nRegistered behind the management auth middleware chain, so a scraper must present\nmanagement credentials (or the route must be added to `client_config.whitelisted_routes`).\n", "tags": [ "Infrastructure" ], "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Prometheus metrics", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/inspect": { "post": { "operationId": "inspectRequest", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| None | Not RBAC-gated - authorized by the credential below |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Inspect a request without forwarding it", "description": "Runs the pre-model plugin checks against a request and answers whether\nforwarding it upstream is allowed, without calling any provider. Intended\nfor an intercepting proxy that holds the original request and needs a\nverdict before releasing it.\n\nPlugins that mutate execution or depend on a provider call are skipped.\n\nUnlike the inference routes, this endpoint takes its request context in\nthe body rather than in HTTP headers: entries in `metadata` are read as\nthe request's headers, so `{\"x-bf-project-id\": \"...\"}` scopes the\ninspected request to a governance project exactly as the header would.\nWhen called with `phase: \"response\"` and `log: true`, the resolved\nproject is recorded on the log row this endpoint writes.\n", "tags": [ "Infrastructure" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A request to evaluate, plus the context the caller would otherwise have sent as HTTP headers.", "required": [ "phase" ], "properties": { "phase": { "type": "string", "enum": [ "request", "response" ], "description": "`request` evaluates before the upstream call; `response` reports the outcome afterwards, which is the phase that can write a log row." }, "log": { "type": "boolean", "description": "Write a log row for this call. Honoured on the `response` phase, where the row carries the resolved governance project." }, "request_id": { "type": "string" }, "session_id": { "type": "string" }, "request": { "type": "object", "additionalProperties": true, "description": "The Bifrost request being inspected." }, "response": { "type": "object", "additionalProperties": true, "description": "The upstream response, on the `response` phase." }, "error": { "$ref": "#/components/schemas/BifrostError" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Read as the inspected request's headers, lowercased. This is how a caller scopes the inspection to a governance project, with `x-bf-project-id` or `x-bf-project-name`." }, "plugin_logs": { "type": "array", "items": { "type": "object", "description": "One line a plugin recorded while evaluating the request.", "properties": { "plugin_name": { "type": "string" }, "level": { "type": "string" }, "message": { "type": "string" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix milliseconds." } } }, "description": "Lines carried over from an earlier phase." } } } } } }, "security": [ { "ManagementBearerAuth": [] } ], "responses": { "200": { "description": "Verdict returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "allow": { "type": "boolean", "description": "Whether forwarding the original request is permitted." }, "reason": { "type": "string", "description": "Why it was refused. Absent when allowed." }, "plugin_logs": { "type": "array", "items": { "type": "object", "description": "One line a plugin recorded while evaluating the request.", "properties": { "plugin_name": { "type": "string" }, "level": { "type": "string" }, "message": { "type": "string" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix milliseconds." } } } } } } } } }, "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/api-keys": { "get": { "operationId": "listAPIKeys", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `APIKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List API keys", "description": "Returns the management API keys, including their scopes and expiry. Key values\nare never returned — only the truncated `key_prefix`.\n\nSupplying any of `limit`, `offset`, or `search` returns a page with\n`total_count` set to the number of matching keys; with no parameters every key\nis returned in one response.\n", "tags": [ "API Keys" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Case-insensitive match against the key name.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of keys to return.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Number of keys to skip.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyList" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ] }, "post": { "operationId": "createAPIKey", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `APIKeys:Create` | RBAC role or API key scope |\n| every permission named in `scopes` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Create an API key", "description": "Creates a management API key and returns its value. The value is shown only in\nthis response and cannot be retrieved afterwards, so store it immediately.\n\nA key's access comes from its `scopes` alone — it does not inherit the\ncreator's role. Beyond `APIKeys:Create`, the caller must already hold every\npermission being granted; requesting one they lack returns 403 and creates\nnothing. A local admin is exempt from that ceiling.\n", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyCreateRequest" } } } }, "responses": { "200": { "description": "Key created. The full key value is returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyCreatedResponse" } } } }, "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" } } } }, "409": { "description": "Conflict with the current state of the resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ] } }, "/api/api-keys/{id}": { "get": { "operationId": "getAPIKey", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `APIKeys:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Get an API key", "description": "Returns one API key by id. The key value is not included — only the truncated\n`key_prefix`.\n", "tags": [ "API Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key id.", "schema": { "type": "integer", "format": "uint" } } ], "responses": { "200": { "description": "The API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyResponse" } } } }, "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": [] }, { "BasicAuth": [] } ] }, "put": { "operationId": "updateAPIKey", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `APIKeys:Update` | RBAC role or API key scope |\n| every permission named in `scopes` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Update an API key", "description": "Updates a key's name, description, scopes, or expiry. The key value itself is\nnever changed — rotating a credential means deleting the key and creating a\nnew one.\n\nOmitted fields keep their current value, with one exception: `description` is\nalways applied, so leaving it out clears any existing description. Sending\n`scopes` replaces the existing list, and the same ceiling as creation applies:\nthe caller must hold every permission being granted. Send `expires_at` as an\nempty string to remove an existing expiry.\n", "tags": [ "API Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key id.", "schema": { "type": "integer", "format": "uint" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyUpdateRequest" } } } }, "responses": { "200": { "description": "The updated API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyResponse" } } } }, "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" } } } }, "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": [] }, { "BasicAuth": [] } ] }, "delete": { "operationId": "deleteAPIKey", "x-mint": { "metadata": { "tag": "Enterprise" }, "content": "\n This endpoint is available in [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) only.\n\n\n**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `APIKeys:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Delete an API key", "description": "Permanently deletes an API key. The key stops authenticating requests across\nthe cluster once the change propagates. This cannot be undone.\n", "tags": [ "API Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key id.", "schema": { "type": "integer", "format": "uint" } } ], "responses": { "200": { "description": "Key deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "API key deleted successfully" } } } } } }, "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": [] }, { "BasicAuth": [] } ] } }, "/api/webhooks": { "get": { "operationId": "listWebhookEndpoints", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ] }, "post": { "operationId": "createWebhookEndpoint", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ] } }, "/api/webhooks/{id}": { "get": { "operationId": "getWebhookEndpoint", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ] }, "put": { "operationId": "updateWebhookEndpoint", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:Update` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ] }, "delete": { "operationId": "deleteWebhookEndpoint", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:Delete` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ] } }, "/api/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookEndpointSecret", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ] } }, "/api/webhooks/{id}/test": { "post": { "operationId": "testWebhookEndpoint", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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" } } } }, "403": { "description": "The endpoint allows private-network delivery and the caller is not authenticated (dashboard auth unconfigured)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BifrostError" } } } } }, "security": [ { "ManagementBearerAuth": [] }, { "BasicAuth": [] } ] } }, "/api/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "List delivery history", "description": "Returns one page of delivery-attempt history for an endpoint, newest first.\n", "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": [] }, { "BasicAuth": [] } ] } }, "/api/webhooks/deliveries": { "get": { "operationId": "searchWebhookDeliveries", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "summary": "Search delivery history", "description": "Returns one page of delivery-attempt history across every endpoint the\nfilters select, newest first. Unlike the per-endpoint\n`/api/webhooks/{id}/deliveries` route, every filter is optional, so an\nunfiltered call returns history for all endpoints.\n\nPagination is by delivery group (`webhook_id`), not by individual attempt:\na page holds every attempt of the deliveries it covers, so `deliveries`\ncan hold more entries than `limit`, and `total_count` counts deliveries\nrather than attempts.\n\nFilters select delivery groups, not attempts — a delivery is on the page\nif any of its attempts matches — and the matched delivery is then returned\nwith its full attempt sequence intact.\n", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint_ids", "in": "query", "required": false, "description": "Comma-separated webhook endpoint ids. Omit for all endpoints.", "schema": { "type": "string" } }, { "name": "events", "in": "query", "required": false, "description": "Comma-separated event names, e.g. `async_job.completed`.", "schema": { "type": "string" } }, { "name": "outcomes", "in": "query", "required": false, "description": "Comma-separated delivery outcomes: `delivered`, `retryable_failure`,\n`permanent_failure`, `exhausted`.\n", "schema": { "type": "string" } }, { "name": "status_class", "in": "query", "required": false, "description": "Comma-separated response status bands: `2xx`, `4xx`, `5xx`, or `none`\nfor attempts where no response arrived. Bands are alternatives (OR).\n", "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "description": "Exact inference request id the delivery was raised for.", "schema": { "type": "string" } }, { "name": "delivery_id", "in": "query", "required": false, "description": "Exact delivery-run id (the `webhook-id` wire header).", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "required": false, "description": "RFC3339 lower bound on attempt time. Ignored when `period` is set.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "description": "RFC3339 upper bound on attempt time. Ignored when `period` is set.", "schema": { "type": "string", "format": "date-time" } }, { "name": "period", "in": "query", "required": false, "description": "Relative window (e.g. `1h`, `24h`) resolved server-side. Takes\nprecedence over `start_time` / `end_time`.\n", "schema": { "type": "string" } }, { "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", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Webhooks:Create` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ] } }, "/api/notifications": { "get": { "operationId": "listNotifications", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Notifications:View` | RBAC role or API key scope |\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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": [] }, { "BasicAuth": [] } ] }, "post": { "operationId": "createNotification", "x-mint": { "content": "**Required Permissions**\n\n| Permission | Granted via |\n| --- | --- |\n| `Notifications:Create` | RBAC role or API key scope |\n| Local admin session | Admin password, or a deployment with dashboard auth disabled |\n\nBoth are required: the handler rejects a caller that is not a local admin\nwith `403 Forbidden` even when the scope is held.\n\n[How permissions work](/api/procuring-api-keys#required-permissions)\n" }, "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. Listing needs just `Notifications:View`, 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": [] }, { "BasicAuth": [] } ] } } }, "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\nwith `Bearer `, where `` is one of:\n\n- a Bifrost management API key,\n- a dashboard session token issued by `POST /api/session/login`,\n- base64 of `:` (legacy equivalent of `BasicAuth`).\n\nVirtual keys (`sk-bf-*`) and the `x-api-key` header are not accepted on management APIs -\nthe sole exception is `GET /api/governance/virtual-keys/quota`, which is virtual-key-only.\n\nAuthentication alone is not sufficient in Bifrost Enterprise: each operation page shows a\n**Required Permissions** table (`Resource:Operation`, for example `Dashboard:View`) above\nits Authorizations section, and the caller's RBAC role or management API key scopes must\ninclude what it lists, otherwise the request is rejected with `403 Forbidden`.\n\nA local admin — authenticated with the admin password, or any caller on a deployment with\ndashboard auth disabled — bypasses these checks and can call every management endpoint.\nSee [Required permissions](/api/procuring-api-keys#required-permissions) for how\npermissions are derived and which endpoints are exempt.\n" }, "BasicAuth": { "type": "http", "scheme": "basic", "description": "Basic authentication using the Bifrost admin username and password\n(`auth_config.admin_username` / `auth_config.admin_password`).\nAccepted on management APIs (`/api/*`, `/metrics`, `/ws`) only - the inference\nmiddleware never validates Basic credentials.\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/*`) - with the single\nexception of the self-service `GET /api/governance/virtual-keys/quota`, where the virtual key is the credential.\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" }, "VirtualKeyBearerAuth": { "type": "http", "scheme": "bearer", "description": "Virtual key passed as a bearer token. The value MUST be an `sk-bf-` prefixed Bifrost\nvirtual key - provider API keys and Bifrost management/session tokens are not accepted\non endpoints that use this scheme.\n" }, "VirtualKeyApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Virtual key passed via the `x-api-key` header. The value MUST be `sk-bf-` prefixed;\nprovider API keys are not accepted on endpoints that use this scheme.\n" }, "VirtualKeyGoogleAuth": { "type": "apiKey", "in": "header", "name": "x-goog-api-key", "description": "Virtual key passed via the Google GenAI `x-goog-api-key` header. The value MUST be\n`sk-bf-` prefixed.\n" }, "VirtualKeyAzureAuth": { "type": "apiKey", "in": "header", "name": "api-key", "description": "Virtual key passed via the Azure-style `api-key` header. The value MUST be\n`sk-bf-` prefixed.\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, and honoured as a fallback\non every `/api/*` management route when no `Authorization` header is sent.\nIt is listed explicitly only on the endpoints where a non-browser client\nrealistically uses it (`/api/session/logout`, `/api/session/ws-ticket`, `/ws`);\nelsewhere prefer `ManagementBearerAuth`.\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": [ "anthropic", "azure", "bedrock", "bedrock_mantle", "cerebras", "cohere", "deepseek", "gemini", "groq", "mistral", "ollama", "opencode-go", "opencode-zen", "openai", "parasail", "perplexity", "sgl", "vertex", "openrouter", "elevenlabs", "huggingface", "nebius", "xai", "replicate", "vllm", "runway", "runware", "fireworks", "sarvam", "wafer", "databricks" ] }, "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" }, "error_type": { "type": "string", "description": "Normalized, low-cardinality classification of why the request failed, declared by whichever component refused it. Prefixed by fault domain (caller_, policy_, provider_, bifrost_). Absent on failures that were not classified at source." } } }, "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "id": { "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" }, "async": { "type": "boolean" }, "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" }, "output_schema": { "type": "object" }, "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" }, "tunnel_id": { "type": "string" }, "allowed_tools": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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" }, "async": { "type": "boolean" }, "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" }, "output_schema": { "type": "object" }, "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" }, "tunnel_id": { "type": "string" }, "allowed_tools": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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" } } }, "DecisionRequest": { "type": "object", "required": [ "model", "state", "questions" ], "properties": { "model": { "type": "string", "description": "Model in provider/model format", "example": "typesafe/jev-1.13.0" }, "state": { "description": "State to evaluate. A plain string, or structured data (object or array).", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "questions": { "type": "object", "minProperties": 1, "description": "Map of named questions. Question identifiers become answer field names.", "additionalProperties": { "$ref": "#/components/schemas/DecisionQuestion" } }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Fallback models in provider/model format" } } }, "DecisionResponse": { "type": "object", "required": [ "model", "answers" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the decision response" }, "model": { "type": "string", "description": "Model that performed the decision" }, "answers": { "type": "object", "description": "Map matching question identifiers to answers. Every requested question produces an answer.", "additionalProperties": { "$ref": "#/components/schemas/DecisionAnswer" } }, "usage": { "$ref": "#/components/schemas/BifrostLLMUsage" }, "extra_fields": { "$ref": "#/components/schemas/BifrostResponseExtraFields" } } }, "DecisionQuestion": { "type": "object", "required": [ "kind", "instructions" ], "properties": { "kind": { "type": "string", "enum": [ "noul", "choice", "score" ], "description": "How the question is decided. `noul` yields a probability between 0 and 1, `choice` yields one option from the criteria, `score` yields a numeric rubric score including fractions." }, "instructions": { "description": "Instructions for this question. A string, or structured data preserved losslessly.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "criteria": { "description": "Applicable criteria. Optional `true`/`false` descriptions for `noul`; a\nrequired map of option to description for `choice` (at most 255 options);\na required ordered array of 2-10 level descriptions for `score`.\n", "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "array", "items": { "type": "string" } } ] } } }, "DecisionAnswer": { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "enum": [ "noul", "choice", "score" ], "description": "The question's decision kind" }, "value": { "description": "The decided value. A number in [0,1] for `noul`, an option string for `choice`, a numeric rubric score for `score`.", "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "confidence": { "type": "number", "description": "Model confidence for this answer, when supplied" }, "probabilities": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Probability distribution over options or levels, when supplied" }, "legend": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Legend mapping levels to descriptions, when supplied" } } }, "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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" }, "async": { "type": "boolean" }, "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" }, "output_schema": { "type": "object" }, "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" }, "tunnel_id": { "type": "string" }, "allowed_tools": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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" }, "async": { "type": "boolean" }, "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" }, "output_schema": { "type": "object" }, "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" }, "tunnel_id": { "type": "string" }, "allowed_tools": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "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" } } }, "mediaResolution": { "type": "object", "description": "Per-part media resolution, overriding generationConfig.mediaResolution for this part alone. Supported on Gemini 3 and later; MEDIA_RESOLUTION_ULTRA_HIGH is image-only.", "properties": { "level": { "type": "string", "enum": [ "MEDIA_RESOLUTION_UNSPECIFIED", "MEDIA_RESOLUTION_LOW", "MEDIA_RESOLUTION_MEDIUM", "MEDIA_RESOLUTION_HIGH", "MEDIA_RESOLUTION_ULTRA_HIGH" ], "description": "The tokenization quality used for the given media" }, "numTokens": { "type": "integer", "format": "int32", "description": "Required sequence length for media tokenization (Gemini API only)" } } } } }, "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 or an empty string disables the grace period, revoking the previous value immediately on the next rotation. 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" }, "azure_deepseek": { "type": "boolean", "default": false, "description": "Convert Azure DeepSeek responses requests to chat completions so reasoning is preserved for coding harnesses" } }, "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 whenever mcp_server_auth_mode is 'both' or 'oauth'. A config.json that enables one of those modes without it fails validation at startup; a PUT /api/config that does the same is refused with HTTP 400. The issuer is never derived from the request Host header while OAuth is enabled. 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", "description": "Proxy URL (http or https). Private and loopback hosts are accepted; link-local and unspecified addresses are rejected." }, "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 or an empty string disables the grace period, revoking the previous value immediately on the next rotation. 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" }, "azure_deepseek": { "type": "boolean", "default": false, "description": "Convert Azure DeepSeek responses requests to chat completions so reasoning is preserved for coding harnesses" } }, "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 whenever mcp_server_auth_mode is 'both' or 'oauth'. A config.json that enables one of those modes without it fails validation at startup; a PUT /api/config that does the same is refused with HTTP 400. The issuer is never derived from the request Host header while OAuth is enabled. 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", "description": "Whether dashboard/admin session authentication is enabled." }, "has_valid_token": { "type": "boolean" }, "auth_type": { "type": "string", "enum": [ "none", "password" ], "description": "Dashboard session auth mode." }, "inference_auth_enforced": { "type": "boolean", "description": "Whether enforce_auth_on_inference is on. This is a separate control from is_auth_enabled. It requires a valid inference credential (virtual key, API key, or user token) on every inference route, including the /v1/* routes and the provider SDK integration routes. A locked dashboard (is_auth_enabled: true) does not by itself protect inference. Check this field too." } } }, "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" }, "does_not_send_done_marker": { "type": "boolean", "description": "Provider ends streams on finish_reason without sending a data: [DONE] marker. Without this, a provider that also keeps the connection open leaves the stream waiting for a marker it never sends." }, "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" } } } }, "prompt_cache": { "type": "object", "description": "Synthesize prompt-cache breakpoints for requests that carry none. Off by default. Requests that already carry their own cache markers are never modified.", "properties": { "auto_inject": { "type": "boolean", "description": "Mark the first cacheable content block, keeping the cached prefix stable across agent turns." }, "ttl": { "type": "string", "enum": [ "1h" ], "description": "Lifetime for injected markers. Omit for the provider default." }, "cache_control_injection_points": { "type": "array", "description": "Target specific messages instead. When set, replaces auto_inject rather than adding to it.", "items": { "type": "object", "description": "One place to add a cache breakpoint. Must set role, index, or both.", "properties": { "location": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant" ] }, "index": { "type": "integer", "description": "Negative values count from the end, so -1 is the last message." } } } } } }, "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" }, "does_not_send_done_marker": { "type": "boolean", "description": "Provider ends streams on finish_reason without sending a data: [DONE] marker. Without this, a provider that also keeps the connection open leaves the stream waiting for a marker it never sends." }, "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" } } } }, "prompt_cache": { "type": "object", "description": "Synthesize prompt-cache breakpoints for requests that carry none. Off by default. Requests that already carry their own cache markers are never modified.", "properties": { "auto_inject": { "type": "boolean", "description": "Mark the first cacheable content block, keeping the cached prefix stable across agent turns." }, "ttl": { "type": "string", "enum": [ "1h" ], "description": "Lifetime for injected markers. Omit for the provider default." }, "cache_control_injection_points": { "type": "array", "description": "Target specific messages instead. When set, replaces auto_inject rather than adding to it.", "items": { "type": "object", "description": "One place to add a cache breakpoint. Must set role, index, or both.", "properties": { "location": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant" ] }, "index": { "type": "integer", "description": "Negative values count from the end, so -1 is the last message." } } } } } } } }, "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" }, "does_not_send_done_marker": { "type": "boolean", "description": "Provider ends streams on finish_reason without sending a data: [DONE] marker. Without this, a provider that also keeps the connection open leaves the stream waiting for a marker it never sends." }, "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" } } } }, "prompt_cache": { "type": "object", "description": "Synthesize prompt-cache breakpoints for requests that carry none. Off by default. Requests that already carry their own cache markers are never modified.", "properties": { "auto_inject": { "type": "boolean", "description": "Mark the first cacheable content block, keeping the cached prefix stable across agent turns." }, "ttl": { "type": "string", "enum": [ "1h" ], "description": "Lifetime for injected markers. Omit for the provider default." }, "cache_control_injection_points": { "type": "array", "description": "Target specific messages instead. When set, replaces auto_inject rather than adding to it.", "items": { "type": "object", "description": "One place to add a cache breakpoint. Must set role, index, or both.", "properties": { "location": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant" ] }, "index": { "type": "integer", "description": "Negative values count from the end, so -1 is the last message." } } } } } } } }, "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). `[\"*\"]` allows every model. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name; an empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400. `blacklisted_models` wins over this list." }, "blacklisted_models": { "type": "array", "items": { "type": "string" }, "description": "List of models this key cannot access (blacklist), which wins over `models`. `[\"*\"]` blocks every model. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name; an empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "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" }, "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" }, "last_failure": { "$ref": "#/components/schemas/MCPConnectionFailure" }, "node_states": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPInstanceState" }, "description": "Per-instance breakdown behind `state` in a distributed deployment:\ninstance ID -> that instance's own self-reported state and\nlast_failure. Present when instances disagree (`state` is then\n`degraded`) and when they all agree on `unstable`, so each instance's\nown reason is visible. Never present 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" }, "require_public_target": { "type": "boolean", "readOnly": true, "default": false, "description": "Server-set. True when the client was registered over the management API\nwith no admin credential check (dashboard auth unconfigured). Every\nconnection to the MCP server (initial, reconnect, per-call) must then\nresolve to a public address. Ignored in create/update request bodies\nand never cleared once set.\n" } } }, "MCPConnectionFailure": { "type": "object", "description": "The latest failure recorded by the instance serving the request for its\nown connection handling of this client: which step failed, the error it\nfailed with, when that last happened, and when the current run of\nfailures began. Present only after that instance has attempted a connect\nor check that failed. Absent while `healthy`, cleared the moment a check\npasses, and absent when a state changed without such an attempt, for\nexample `needs_reauth` projected from a credential row that died before\nthe next scheduled check ran. Describes only Bifrost's own connection\nchecks and connect attempts, never the outcome of real tool calls made\nthrough the client.\n", "required": [ "stage", "message", "at", "since" ], "properties": { "stage": { "type": "string", "enum": [ "connect", "ping", "list_tools", "tool_discovery", "transport_lost", "credential" ], "description": "The step that failed:\n- connect: establishing the shared connection (dial, initialize,\n connect gate, or the initial list_tools a new connection must pass)\n- ping: the periodic check's ping over an existing sticky connection\n- list_tools: the periodic check's list_tools over an existing sticky\n connection\n- tool_discovery: the periodic check's ephemeral connect-discover-close\n cycle for per-call auth types\n- transport_lost: a live SSE connection dropped outside any check\n- credential: a credential the connection depends on was rejected\n upstream or rotated by an admin\n" }, "message": { "type": "string", "description": "The error the step failed with, whitespace-collapsed and capped at 512 characters." }, "at": { "type": "string", "format": "date-time", "description": "The most recent failed attempt. While a client is unstable the check\nretries every 10 seconds, so this keeps moving for as long as the\noutage lasts.\n" }, "since": { "type": "string", "format": "date-time", "description": "The first failed attempt of the current unhealthy run." } } }, "MCPInstanceState": { "type": "object", "description": "One instance's own view of an MCP client in a distributed deployment.", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "healthy", "unstable", "error", "pending_verification", "needs_reauth", "disabled" ], "description": "That instance's own self-reported connection state. Never `degraded`,\nwhich only ever exists as the aggregate above this map.\n" }, "last_failure": { "$ref": "#/components/schemas/MCPConnectionFailure" } } }, "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" }, "allow_all_providers": { "type": "boolean", "description": "When true, this virtual key may use every configured provider. provider_configs still apply as optional per-provider overrides (budgets, rate limits, model allow/blacklists, key selection); a provider without a config gets all models, all keys, and no per-provider limits.\n" }, "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" }, "assigned_user": { "type": [ "object", "null" ], "readOnly": true, "description": "The user this virtual key is assigned to, or null when it is assigned to a team, a customer, or nothing. Read-only and resolved per request. Enterprise only; always null in the open-source build, which has no user directory. Omitted entirely when the assignee lookup could not be completed, so null always means \"nobody is assigned\" and an absent field means \"not known\" - clients should refetch the assignee for the key rather than reading its absence as unassigned.\n", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, "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" }, "description": "Allowlist. `[\"*\"]` allows every model. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks every model. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "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", "rate_limits", "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" } } } }, "source_type": { "type": "string", "description": "What governs this budget when it did not come from the virtual key's own rows — e.g. `access_profile`. Omitted when there is nothing to disambiguate.\n" }, "source_id": { "type": "string", "description": "ID of the source named by `source_type`." }, "source_name": { "type": "string", "description": "Human-readable label for `source_id`." } } } ] } }, "rate_limit": { "description": "The single effective rate limit for this key. For a key managed by an enterprise access profile this is the tightest-per-dimension merge of every profile governing the key, and carries the real usage. Kept for readers that expect one value; see `rate_limits` for the unmerged list.\n", "oneOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "null" } ] }, "rate_limits": { "type": "array", "description": "Every rate limit `rate_limit` was merged from, each tagged with its source, so a caller can see which one is actually binding rather than only the merged result. A user may hold several enterprise access profiles at once, each contributing its own rate limit, so this can carry more than one entry. Always present; empty when the key has no rate limit at all.\n", "items": { "description": "A rate limit tagged with what governs it. The source fields are empty when there is nothing to disambiguate, e.g. a virtual key's own rate-limit row.\n", "allOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "object", "properties": { "source_type": { "type": "string", "description": "What governs this rate limit — e.g. `access_profile`." }, "source_id": { "type": "string", "description": "ID of the source named by `source_type`." }, "source_name": { "type": "string", "description": "Human-readable label for `source_id`." } } } ] } }, "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. When allow_all_providers is omitted or false, an empty list allows no providers (deny-by-default); when true, providers without a config are allowed with all models and keys.", "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" }, "description": "Allowlist. `[\"*\"]` allows every model. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks every model. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "budgets": { "type": "array", "description": "Provider-specific budget quotas. Use this array instead of the removed singular `budget` or `budget_id` fields.", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/CreateRateLimitRequest" }, "key_ids": { "type": "array", "description": "Provider API key IDs allowed for this config. `[\"*\"]` allows every key for the provider; an empty or omitted array denies all keys.", "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. Use this array instead of the removed singular `budget` or `budget_id` fields.", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/CreateRateLimitRequest" }, "is_active": { "type": "boolean" }, "calendar_aligned": { "type": "boolean", "default": false }, "allow_all_providers": { "type": "boolean", "default": false, "description": "When true, this virtual key may use every configured provider. provider_configs remain optional per-provider overrides for budgets, rate limits, model allow/blacklists, and key selection.\n" }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional expiry timestamp. Must be in the future. Omit for a key that never expires." } }, "example": { "name": "engineering-vk", "provider_configs": [ { "provider": "openai", "weight": 1, "allowed_models": [ "gpt-4o-mini" ], "key_ids": [ "*" ], "budgets": [ { "max_limit": 50, "reset_duration": "1M" } ] } ], "budgets": [ { "max_limit": 100, "reset_duration": "1M" } ], "is_active": true } }, "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" }, "description": "Allowlist. `[\"*\"]` allows every model. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "blacklisted_models": { "type": "array", "items": { "type": "string" }, "description": "Denylist, which wins over the allowlist. `[\"*\"]` blocks every model. An entry starting with `regex:` is an RE2 pattern matched case-insensitively against the whole model name. An empty pattern, `regex:*`, or a pattern that does not compile is rejected with 400." }, "budgets": { "type": "array", "description": "Provider-specific budget quotas. Replaces all budgets for that provider config when provided; the removed singular `budget` and `budget_id` fields are not request fields.", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/UpdateRateLimitRequest" }, "key_ids": { "type": "array", "description": "Provider API key IDs allowed for this config. `[\"*\"]` allows every key for the provider; an empty or omitted array denies all keys.", "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; the removed singular `budget` and `budget_id` fields are not request fields.", "items": { "$ref": "#/components/schemas/CreateBudgetRequest" } }, "rate_limit": { "$ref": "#/components/schemas/UpdateRateLimitRequest" }, "is_active": { "type": "boolean" }, "calendar_aligned": { "type": "boolean" }, "allow_all_providers": { "type": "boolean", "description": "When true, this virtual key may use every configured provider. provider_configs remain optional per-provider overrides. Omit to leave the current setting unchanged.\n" }, "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." } }, "example": { "description": "Updated engineering access", "provider_configs": [ { "provider": "openai", "weight": 1, "allowed_models": [ "gpt-4o", "gpt-4o-mini" ], "key_ids": [ "*" ], "budgets": [ { "max_limit": 75, "reset_duration": "1M" } ] } ], "budgets": [ { "max_limit": 150, "reset_duration": "1M" } ] } }, "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 }, "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": { "description": "A fallback in a routing rule's chain. Either the \"provider/model\" string (\"provider/\" keeps the incoming model), or an object that additionally pins a provider key.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Fallback provider" }, "model": { "type": [ "string", "null" ], "description": "Fallback 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 fallback (omit for load-balanced key selection). A fallback whose pinned key is missing from the provider's pool is skipped." } }, "additionalProperties": false } ] }, "description": "Ordered fallback chain, tried after the selected target fails" }, "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": { "description": "A fallback in a routing rule's chain. Either the \"provider/model\" string (\"provider/\" keeps the incoming model), or an object that additionally pins a provider key.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Fallback provider" }, "model": { "type": [ "string", "null" ], "description": "Fallback 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 fallback (omit for load-balanced key selection). A fallback whose pinned key is missing from the provider's pool is skipped." } }, "additionalProperties": false } ] }, "description": "Ordered fallback chain, tried after the selected target fails" }, "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": { "description": "A fallback in a routing rule's chain. Either the \"provider/model\" string (\"provider/\" keeps the incoming model), or an object that additionally pins a provider key.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "minLength": 1, "description": "Fallback provider" }, "model": { "type": [ "string", "null" ], "description": "Fallback 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 fallback (omit for load-balanced key selection). A fallback whose pinned key is missing from the provider's pool is skipped." } }, "additionalProperties": false } ] }, "description": "Ordered fallback chain, tried after the selected target fails" }, "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; `project` scopes to a governance project (Enterprise only); `access_profile` rows are materialized from an access profile and are read-only here, editable only through the profile's own override endpoints (Enterprise only); `user` is a legacy per-user scope that can no longer be created (Enterprise only).", "enum": [ "global", "virtual_key", "project", "access_profile", "user" ], "default": "global" }, "scope_id": { "type": "string", "nullable": true, "description": "ID of the scope target — a virtual key ID for `virtual_key`, a user access profile ID for `access_profile`, a user ID for legacy `user` rows. Required when scope is not `global`.\n" }, "scope_name": { "type": "string", "nullable": true, "description": "Resolved human-readable name of the scope target (read-only, set by server)." }, "source_type": { "type": "string", "description": "What materialized this limit, when it was not authored directly — e.g. `access_profile`. Read-only; omitted for limits with no upstream source.\n" }, "source_id": { "type": "string", "description": "ID of the source named by `source_type` (read-only)." }, "source_name": { "type": "string", "description": "Human-readable label for `source_id` (read-only)." }, "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`. `project` targets a governance project (Enterprise only). The legacy `user` scope is refused on create; use an access profile instead.", "enum": [ "global", "virtual_key", "project" ], "default": "global" }, "scope_id": { "type": "string", "description": "ID of the scope target, for example a virtual key id or a project 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_ultrafast": { "type": "number", "minimum": 0 }, "output_cost_per_token_ultrafast": { "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 }, "input_cost_per_token_above_272k_tokens_ultrafast": { "type": "number", "minimum": 0 }, "output_cost_per_token_above_272k_tokens_ultrafast": { "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_ultrafast": { "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_read_input_token_cost_above_272k_tokens_ultrafast": { "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_above_272k_tokens_priority": { "type": "number", "minimum": 0, "description": "Cache creation above 272k context for priority (OpenAI Fast mode) requests." }, "cache_creation_input_token_cost_ultrafast": { "type": "number", "minimum": 0 }, "cache_creation_input_token_cost_above_272k_tokens_ultrafast": { "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 }, "output_cost_per_video_per_second_480p": { "type": "number", "minimum": 0, "description": "Per-second output rate for 480p video. Matched on the short edge of the generated video's size; falls back to output_cost_per_video_per_second when unset." }, "output_cost_per_video_per_second_720p": { "type": "number", "minimum": 0, "description": "Per-second output rate for 720p video. Matched on the short edge of the generated video's size; falls back to output_cost_per_video_per_second when unset." }, "output_cost_per_video_per_second_1024p": { "type": "number", "minimum": 0, "description": "Per-second output rate for 1024p video. Matched on the short edge of the generated video's size; falls back to output_cost_per_video_per_second when unset." }, "output_cost_per_video_per_second_1080p": { "type": "number", "minimum": 0, "description": "Per-second output rate for 1080p video. Matched on the short edge of the generated video's size; falls back to output_cost_per_video_per_second when unset." }, "output_cost_per_video_per_second_4k": { "type": "number", "minimum": 0, "description": "Per-second output rate for 4K video. Matched on the short edge of the generated video's size; falls back to output_cost_per_video_per_second when unset." }, "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 }, "off_peak_cost_multiplier": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "Multiplier applied to every usage-based charge when the request falls outside the windows declared in peak_hours. Every other rate on this object is the peak (higher) price, so this can only scale downward — e.g. 0.5 for a 50% off-peak discount. Flat per-request and per-query fees are not discounted. A discount applies only when the RESOLVED pricing row carries both this field and peak_hours. A patch may supply one and inherit the other from the model's datasheet entry, so setting this alone still discounts when the datasheet already declares a schedule; it bills at peak only when neither source provides one.\n" }, "peak_hours": { "type": "object", "description": "Recurring weekly windows during which the model is billed at its peak (base) rates. Any instant outside every window is off-peak and is discounted by off_peak_cost_multiplier. Peak vs off-peak is decided by the request's start time, so a stream crossing a boundary bills entirely at its start-time rate.\n", "properties": { "timezone": { "type": "string", "description": "IANA location name (e.g. \"UTC\", \"Asia/Shanghai\"). Empty means UTC.", "example": "UTC" }, "windows": { "type": "array", "description": "At least one window is required. A schedule with no usable window cannot be evaluated, and an unevaluable schedule bills at peak, so an empty list would silently discard the discount rather than make every instant off-peak.\n", "minItems": 1, "items": { "type": "object", "properties": { "days": { "type": "array", "description": "Weekdays the window applies to, 0 = Sunday through 6 = Saturday. For a window that wraps past midnight, this is the weekday the window starts on. At least one is required, for the same reason windows itself is.\n", "minItems": 1, "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "example": [ 1, 2, 3, 4, 5 ] }, "start": { "type": "string", "description": "Window start as \"HH:MM\" in the schedule's timezone (inclusive).", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "01:00" }, "end": { "type": "string", "description": "Window end as \"HH:MM\" in the schedule's timezone (exclusive). A value less than or equal to start wraps past midnight. \"24:00\" is accepted as an end-of-day marker.\n", "pattern": "^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$", "example": "04:00" } }, "required": [ "days", "start", "end" ] } } }, "required": [ "windows" ] } } }, "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" }, "project_id": { "type": "string", "nullable": true, "description": "The governance project the request was scoped to, or null when it named none. This is the resolved project, not the header the caller sent." }, "project_name": { "type": "string", "nullable": true, "description": "The project's name as it stood when the request was served, kept on the row so it still reads correctly after a rename or a delete." }, "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)" }, "tool_call_names": { "type": "array", "items": { "type": "string" }, "description": "Distinct function names the response called. Always recorded, even when content logging is disabled, and kept on the log row in hybrid storage mode. Use the tool_call_names query filter to search on it. Full tool calls with arguments are in tool_calls and are available only when content is retained.", "nullable": true }, "routing_rule_id": { "type": "string", "nullable": true }, "routing_rule_name": { "type": "string", "nullable": true }, "complexity_tier": { "type": "string", "enum": [ "SIMPLE", "MEDIUM", "COMPLEX", "REASONING" ], "description": "Complexity tier used for routing; null when no routing rule referenced complexity_tier. REASONING is historical-only — it was merged into COMPLEX and is never emitted for new requests, but survives in log rows recorded under the old scheme.", "nullable": true }, "complexity_mechanism": { "type": [ "string", "null" ], "enum": [ "semantic", "llm", "session", "skipped", null ], "description": "How the effective complexity tier was determined. session means retained session state supplied the tier; skipped means classification was demanded but produced no tier." }, "complexity_score": { "type": "number", "description": "Similarity score of the nearest reference phrase behind the tier. Absent for llm, session, and skipped decisions.", "nullable": true }, "session_id": { "type": "string", "description": "Raw opaque Bifrost session ID resolved at ingress for key stickiness and request correlation.", "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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" } } } ] }, "async": { "type": "boolean" }, "action": { "type": "object" }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "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" } } }, "LogStatsResponse": { "description": "Log statistics for the requested window. The current period's fields are at the top level, so a request without `compare_to_previous` returns exactly the LogStats shape.", "allOf": [ { "$ref": "#/components/schemas/LogStats" }, { "type": "object", "properties": { "has_previous_period": { "type": "boolean", "description": "True when `previous` is populated. False when the comparison was not requested, the window is unbounded, or the previous-period query failed." }, "previous": { "allOf": [ { "$ref": "#/components/schemas/LogStats" } ], "description": "The same statistics for the preceding window of equal length, ending immediately before the requested window starts. Present only when `compare_to_previous` is true and `has_previous_period` is true." } } } ] }, "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": { "allOf": [ { "type": "object", "description": "Log search filters", "properties": { "project_ids": { "type": "array", "items": { "type": "string" }, "description": "Governance projects to narrow to. A request is scoped to at most one project, so this filter selects rows rather than intersecting sets." }, "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" } } }, { "type": "object", "properties": { "period": { "type": "string", "enum": [ "1h", "6h", "24h", "7d", "30d" ], "description": "Relative time window resolved when the job is created. When recognized, it takes precedence over start_time and end_time." } } } ] } } }, "RecalculateCostResponse": { "type": "object", "description": "Recalculate cost job status", "properties": { "id": { "type": "string", "description": "Background job ID" }, "status": { "type": "string", "description": "Current job status", "enum": [ "pending", "running", "completed", "failed", "cancelled", "idle" ] }, "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" }, "unpriceable": { "type": "integer", "format": "int64", "description": "Subset of skipped logs whose pricing inputs could not be recovered, so their existing cost was left unchanged." }, "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" ] }, "APIKey": { "type": "object", "description": "A management API key. The key value itself is never returned after creation —\nonly the truncated `key_prefix` is, so keys can be told apart in a list.\n", "properties": { "id": { "type": "integer", "format": "uint", "description": "Server-assigned identifier, used in the path of the by-id routes." }, "name": { "type": "string", "description": "Unique, human-readable name." }, "key_prefix": { "type": "string", "description": "Truncated, non-secret form of the key for display, such as\n`bfst-A1b2C3d4...`. Not accepted for authentication.\n", "example": "bfst-A1b2C3d4..." }, "description": { "type": "string", "nullable": true, "description": "Optional free-text note about what the key is for." }, "scopes": { "type": "array", "items": { "type": "integer", "format": "uint" }, "description": "Permission ids granted to this key. Each id is an RBAC (resource, operation)\npair from `GET /api/governance/rbac/permissions`.\n" }, "created_by_user_id": { "type": "string", "nullable": true, "description": "User who created the key. Null when the deployment has no user identity on\nthe request (no-auth, password-only, or local-admin modes).\n" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiry timestamp, or null if the key never expires." }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last time the key authenticated a request, or null if never used." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "APIKeyScopes": { "type": "array", "items": { "type": "integer", "format": "uint" }, "description": "Permission ids to grant, from `GET /api/governance/rbac/permissions`. A key\ncarries only the permissions listed here — the creator's own role is not\ninherited. You cannot grant a permission you do not hold yourself; doing so\nreturns 403.\n" }, "APIKeyCreateRequest": { "type": "object", "required": [ "name" ], "description": "Create body for a management API key. The key value is generated by the server\nand can never be supplied here.\n", "properties": { "name": { "type": "string", "description": "Unique name for the key." }, "description": { "type": "string", "nullable": true, "description": "Optional note about what the key is for." }, "scopes": { "$ref": "#/components/schemas/APIKeyScopes" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiry timestamp in RFC3339 format. Omit or send null for a key that never\nexpires.\n" } } }, "APIKeyUpdateRequest": { "type": "object", "description": "Update body for a management API key. Every field is optional; the key value\nitself can never be changed here.\n", "properties": { "name": { "type": "string", "description": "New name for the key. Omit it, or send an empty string, to keep the\ncurrent name.\n" }, "description": { "type": "string", "nullable": true, "description": "Note about what the key is for. This field is always applied, so omitting\nit clears any existing description — send the current value to preserve it.\n" }, "scopes": { "allOf": [ { "$ref": "#/components/schemas/APIKeyScopes" } ], "description": "Replaces the key's scopes in full. Omit to leave the current scopes\nunchanged. Permission ids come from\n`GET /api/governance/rbac/permissions`, and you can only grant permissions\nyou hold yourself.\n" }, "expires_at": { "nullable": true, "description": "New expiry. Send an RFC3339 timestamp to set one, an empty string to\nremove an existing expiry, or omit the field to leave it unchanged.\n", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "enum": [ "" ], "description": "Clears the existing expiry." } ] } } }, "APIKeyResponse": { "type": "object", "properties": { "api_key": { "$ref": "#/components/schemas/APIKey" } } }, "APIKeyCreatedResponse": { "type": "object", "description": "Creation response. This is the only time the full key value is returned —\nstore it immediately, as it cannot be retrieved again.\n", "properties": { "api_key": { "$ref": "#/components/schemas/APIKey" }, "key": { "type": "string", "description": "The full key value, shown only once. Send it in the `Authorization` header\nas `Bearer `.\n", "example": "bfst-A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2" } } }, "APIKeyList": { "type": "object", "properties": { "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } }, "count": { "type": "integer", "description": "Number of keys in this response." }, "total_count": { "type": "integer", "description": "Total keys matching the query. Equal to `count` unless a paginated request\n(`limit`, `offset`, or `search`) was made.\n" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "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" } } } } } }